home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 22 / Amiga Format AFCD22 (Jan 1998, Issue 106).iso / -seriously_amiga- / shareware / programming / other / cop / cop.doc < prev    next >
Text File  |  1997-11-05  |  122KB  |  2,479 lines
  1. $VER: COP Doc 1.11
  2. *****************************************************************************
  3. **                                                                         **
  4. ** ___________                                                             **
  5. ** \        */                                                             **
  6. **  /-----------     #######     #######    ########                       **
  7. **  |    ^ |        ##      ##  ##     ##   ##     ##                      **
  8. **  |      _\       ##          ##     ##   ##     ##  Version 1.58        **
  9. **  |      |        ##          ##     ##   ########                       **
  10. **  |    --|        ##          ##     ##   ##                             **
  11. **  +-----/         ##      ##  ##     ##   ##                             **
  12. **   |   |           #######     #######    ## (c) 1993-1997 THOR-Software **
  13. **                                                                         **
  14. **                                                                         **
  15. **              A Low Level Debugger for all Amiga Systems                 **
  16. **                                                                         **
  17. *****************************************************************************
  18.  
  19.                                     by
  20.  
  21.      _______         _____  _____           __     _
  22.         /    /    / /    / /    /         \/_/    //_/_
  23.        /    /____/ /    / /____/   ___    /  ____// /        _      __
  24.       /    /    / /    / /   \           /  /|/ /  /  /   /_/ / /\_/_/
  25.      /    /    / /____/ /    /         _/__/_/ /__/|_/_/_/ /_/_/  /_
  26.                                               /                   
  27.  
  28.  
  29.  
  30. +-----------------------------------------------------------------------+
  31. |                                                                       |
  32. |       This release of COP is full FREEWARE...                         |
  33. |        ...but possibly the next release won't.                        |
  34. |                                                                       |
  35. |       You are free to copy this program, as long as:                  |
  36. |                                                                       |
  37. | - All files in this drawer are included.                              |
  38. | - ALL COMERCIAL USE IS STRICTLY PERMITED :                            |
  39. |       DON'T SELL WITHOUT PERMISSION OF THE AUTHOR !                   |
  40. |       DON'T INCLUDE IN COMERCIAL PRODUCTS OR ARCHIVES WITHOUT         |
  41. |       PERMISSIONS OF THE AUTHOR !                                     |
  42. |                                                                       |
  43. | This  program  is  provided "as is" without warranty of any kind.     |
  44. | The entire risk  of using it is to the user himself.  In no event I   |
  45. | will be liable  for  direct or indirect damage, loss of data or       |
  46. | criminal actions done due  to  the use of this program.               |
  47. | If you do not agree with this, you must not use COP.                  |
  48. |                                                                       |
  49. +-----------------------------------------------------------------------+
  50.  
  51. _____________________________________________________________________________
  52.  
  53.                         The THOR-Software Licence
  54.  
  55.  
  56. This License applies to the computer programs known as "COP".
  57. The "Program", below, refers to such program.
  58.  
  59.  
  60. The programs and files in this distribution are freely distributable
  61. under the restrictions stated below, but are also Copyright (c)
  62. Thomas Richter.
  63.  
  64.  
  65. Distribution of the Program by a commercial organization without written
  66. permission from the author to any third party is prohibited if any payment
  67. is made in connection with such distribution, whether directly
  68. (as in payment for a copy of the Program) or indirectly (as in payment
  69. for some service related to the Program, or payment for some product
  70. or service that includes a copy of the Program "without charge";
  71. these are only examples, and not an exhaustive enumeration of prohibited
  72. activities). However, the following methods of distribution involving
  73. payment shall not in and of themselves be a violation of this restriction:
  74.  
  75.  
  76. (i) Posting the Program on a public access information storage and
  77. retrieval service for which a fee is received for retrieving information
  78. (such as an on-line service), provided that the fee is not
  79. content-dependent (i.e., the fee would be the same for retrieving the same
  80. volume of information consisting of random data).
  81.  
  82.  
  83.  
  84. (ii) Distributing the Program on a CD-ROM, provided that the files
  85. containing the Program are reproduced entirely and verbatim on such
  86. CD-ROM, and provided further that all information on such CD-ROM be
  87. redistributable for non-commercial purposes without charge.
  88.  
  89.  
  90.  
  91. Everything in this distribution must be kept together, in original
  92. and unmodified form.
  93.  
  94.  
  95.  
  96.  
  97. Limitations.
  98.  
  99. THE PROGRAM IS PROVIDED TO YOU "AS IS," WITHOUT WARRANTY. THERE IS NO
  100. WARRANTY FOR THE PROGRAM, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT
  101. LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
  102. PARTICULAR PURPOSE AND NONINFRINGEMENT OF THIRD PARTY RIGHTS. THE ENTIRE
  103. RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD
  104. THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY
  105. SERVICING, REPAIR OR CORRECTION.
  106.  
  107.  
  108.  
  109. IF YOU DO NOT ACCEPT THIS LICENCE, YOU MUST DELETE ALL FILES CONTAINED IN
  110. THIS ARCHIVE.
  111.  
  112. _____________________________________________________________________________
  113.  
  114.  
  115. I) Who should use COP ?
  116. ------------------------
  117.  
  118. - If you prefer working with the workbench or if you write programs in
  119.   pascal or (ARGH) basic, if you do not know how to use an assembler 
  120.   or are not familiar with bits and bytes, if you hate command interpreters 
  121.   and like funny gadgets and colorful menus, if you do not know the ASCII
  122.   character codes by heart :
  123.   
  124.   **======================================================**
  125.   || FORGET IT ! STOP NOW ! YOU WON'T BE HAPPY WITH COP ! ||
  126.   **======================================================**  
  127.  
  128.   To make it short: COP is intended to be used by REAL MEN ! (-;
  129.   (or WOMEN...)
  130.  
  131.         (Suggested: "Real men don't eat quiche" available on
  132.          in good networks...)
  133.   
  134. II) COP Features
  135. ----------------
  136.  
  137. Let's start with the bad ones:
  138.  
  139.         o)      it looks like an old-time debugger and feels like one, too
  140.         o)      there's no graphic user interface
  141.         o)      it's based on a command interpreter
  142.         o)      it's hard to learn
  143.         o)      it supports the MMU only partially, although this is getting
  144.         better. The MC68040 and up MMU is completely unssupported
  145.         as I have no documents about it.
  146.                 (STOP HERE IF YOU DO NOT KNOW THE WORD "MMU" !)
  147.         o)      it should support almost all MC68xxx, although I
  148.                 haven't tested it
  149.         o)      some features are available only with additional
  150.                 hardware, e.g. a MC68010 or higher or an external
  151.                 terminal
  152.         o)      some commands are available only with the 2.0 roms or better
  153.         o)      the build-in terminal emulation isn't a fast one
  154.                 and does use non-standard command sequences
  155.         o)      it does not handle fragmented memory models in a
  156.                 good way, although it's getting better
  157.         o)      there is no trackdisk or harddisk support and there
  158.                 never will
  159.         o)      it does not use task switching, but busy-waits
  160.                 (ARGHH!)
  161.                 
  162.         Some of the points WILL change in the future, I promise...
  163.  
  164.                 
  165. ...and now the good ones:
  166.         o)      it does support all members of the MC68000-family,
  167.                 at least it should...
  168.                 (MC680000 thru MC68060 including FPUs, but not
  169.                  yet the MMU of the MC68040 and MC68060 - sorry....)
  170.         o)      it provides a break key that can be assigned to
  171.                 all (well, almost all) keys on the keyboard
  172.                 and that breaks almost everthing everytime.
  173.         o)      it uses hardware resources as less as possible
  174.                 (e.g. no blitter acesses, no copper on request)
  175.         o)      COP can be used to remote-debug a system over a
  176.                 serial connection, leaving the display and keyboard
  177.                 hardware to other programs
  178.         o)      COP catches almost all system crashes ("GURUs")
  179.         o)      COP can be used to debug almost all code, even 
  180.                 interrupts are NO problem (is there a second
  181.                 debugger who can ?)
  182.         o)      it can be made resident to debug startup code
  183.         o)      it supports symbols in its own language and
  184.                 the symbols in object modules. Source level
  185.                 debugging, however, is not supported.
  186.         o)      it has a funny documentation in broken english
  187.                 (speak you english ?)
  188.         o)      this new release supports printers, connected either to
  189.                 the parallel port of your Amiga or to an external terminal,
  190.                 provided it supports the new COP 5 terminal standard
  191.                 (see terminal.doc in this archive for more information)
  192.         o)      it can be loaded to a memory position of your choice,
  193.                 although the arguments are a bit tricky 
  194.         o)      it's free, at least this release...
  195.         o)      it steps thru everything, even interrupt code and
  196.                 supervisor programs. YES, exec's task scheduler is
  197.                 NO PROBLEM AT ALL.
  198.         o)      it can be used as a shell calculator and
  199.                 as a label database.
  200.         o)      it supports symbols in standard overlay segments
  201.                 (which other debugger does ?)
  202.         o)      it supports debugging of CLI/WB progs in C and BCPL
  203.                 thru a simplified interface
  204.         o)      it works in really almost all situations, even
  205.                 with execbase broken...
  206.         o)      it supports the ShapeShifter 
  207.     o)    it is compatible to the Enforcer if used with a MC68020 or
  208.         MC68030. It does, however, not support the CyberGuard, at
  209.         least I had no chance to test it.
  210.  
  211.         
  212.         ...and if I say "almost all" I mean: more than any other
  213.         debugger can, but I am honest: There are situations where
  214.         COP CAN crash, but they are VERY rare.        
  215.  
  216.  
  217. III) Before you start, you need to provide...
  218. -----------------------------------------------------------------------------
  219. (or, in other words: NOT included in this package...)
  220.  
  221. - a lot of good will and your brain. COP is not easy to use...
  222. - this manual. Or to make it clear : READ THIS FIRST BEFORE YOU
  223.   START PLAYING WITH COP. There's a good chance you'll crash your
  224.   system.
  225. - an amiga computer with at least 512K. The more memory, the better.
  226. - If you want that magic break feature : A processor MC68010 or
  227.   higher would be fine. The break key does not work in all situations
  228.   with the standard MC680000.
  229. - If you need all commands (e.g. task capture and task freeze), you need
  230.   commodore's 2.0 roms or better.
  231. - If the program to debug needs the display subsystem, you need at least
  232.   an external serial tty terminal.
  233. - If you want a fancier and better user interface, the external terminal
  234.   should understand type-3 terminal commands or better. Cause this is
  235.   a private format, there are not many... :-)
  236.   You may write your own terminal, or use the one supplied in this
  237.   package, see "terminal.doc".
  238. - If you need printer output, you need either a printer connected to the
  239.   parallel port of your Amiga or a printer connected to an external type-5
  240.   terminal or tty-terminal with printer-support. Any printer will do, COP
  241.   outputs only plain 7-bit ASCII.
  242.   Use the following configuration for your printer:
  243.         
  244.         o) data input from parallel interface
  245.         o) Auto-LF on, CR disabled (Auto-CR does not care)
  246.  
  247.   This is, however, the most common setting, so just try. The normal setting
  248.   will work in most situations without any change.
  249.  
  250.   If you MUST use the Amiga parallel port, use the command line switch
  251.   BUILDINPRT or the IOCD.Q command to disable external printing.
  252.    
  253.  
  254. IV) Installing COP in your system
  255. -----------------------------------------------------------------------------
  256.  
  257. If you want to remote-debug your system: connect an external ASCII-terminal
  258. to the serial plug. Set the external terminal to the following parameters:
  259.  
  260. 9600 baud, 8 bit, 1 stop bit, no parity,
  261. no auto LF, no auto CR, non-erasing BS
  262.  
  263. If your external terminal supports printers, connect the printer to THIS
  264. terminal, not to the Amiga; if not, connect the printer to the parallel port
  265. of the Amiga and use the IOCD.Q command or the command line option 
  266. BUILDINPRT to tell COP to use the build-in printer-routines.
  267.  
  268. Copy the COP file to the C:-drawer of your system disk and, if you like to
  269. start COP from the workbench, copy the COP-icon anywhere you want (it is
  270. not necessary, only a nice feature ).
  271.  
  272. Copy the shell scripts "Debug","WBDebug" and "Calc" to the S: drawer,
  273. put this file in a save place wherever you want.
  274.  
  275. If you have commodore's V40 includes, copy the default data description
  276. table "Startup.DDT" to S:. You might want to modify it a bit, for example
  277. to correct the pathes. This file currently expects the FD files in a
  278. device FD:, and the includes in INCLUDE:
  279.  
  280. If you want to run COP with the shapeshifter, copy the file "Mac.DDT" to
  281. S:, too.
  282.  
  283. Insert in your startup-sequence DIRECTLY FOLLOWING to the "SetPatch"-command
  284. (this is the second line for most systems) a command like the following:
  285.  
  286. COP keymap usa display resident ddt s:startup.ddt
  287.  
  288. What does this mean:
  289. -The build-in terminal uses the keymap "usa". If you prefer a different
  290.  keymap, change "usa" to your favourite keymap that must be present in
  291.  the DEVS:keymaps drawer of your system.
  292.  YOU CAN'T CHANGE THAT KEYMAP WITH A "SETMAP" or "SETKEYBOARD" or the 
  293.  PREFERENCE PROGRAM LATER !
  294.  COP OPERATES INDEPENDED FROM THE REMAINDING SYSTEM !
  295.  
  296. -The "display" command tells COP to use the build-in terminal instead of an
  297.  external one. You can debug programs with the amiga keyboard on the amiga
  298.  monitor. If you want to remote-debug, use "serial" instead. If you've got
  299.  an external tty, I would suggest to do so.
  300.  
  301. -The "resident" keyword tells COP to stay resident even after reset. If
  302.  you do not need this feature: drop this argument. Loading COP as resident
  303.  program has the advantage that you can debug boot code.
  304.  
  305. -The "ddt" keyword loads the standard labels placed in the ddt-file and
  306.  commodore's include files into COP. If you don't have them:
  307.  Never mind, just delete the the last two arguments.
  308.  
  309. More about the command argument line later... (chapter XI)
  310.  
  311. You should also start the workbench with the "-debug" option to have COP
  312. ready in all situations.
  313.  
  314. Save the modified startup-sequence and reboot your system. Not much to
  315. see? O.K., that's normal. COP is NOT a standard debugger and is only
  316. INSTALLED by the command line, but not STARTED.
  317.  
  318.  
  319.  
  320. V) How to start COP
  321. -----------------------------------------------------------------------------
  322.  
  323. There are many ways to begin a debug session with COP:
  324. -Double-click the COP-Icon, if you copied it to your system.
  325. -Enter in the shell the command:
  326.         COP go
  327. -Select the "ROMWack" (or "Debug") menu of the workbench. COP replaces
  328.  the old wack completly, if there was one installed in your ROM.
  329.  (Commodore removed the old ROM-Wack from the 3.1 Roms and replaced it
  330.  with the "SAD" debugger.)
  331. -Press the BREAK-key. In the build-in terminal - if you supplied the
  332.  "display" argument above - this is the decimal dot of the numeric key-
  333.  pad. On external terminals, it's ESC. However, you may change that key
  334.  with an additional argument, see chapter XI.
  335. -Use the shell-scripts "Debug" and "WBDebug" to load programs,
  336.  symbols and start a debug session like with every other debugger.
  337.  Up to eight arguments are allowed here as CLI arguments, resp. one as
  338.  an extended selection icon "clicked" with the main icon.
  339. -The least pleasant way : Your system crashes and COP is entered auto-
  340.  matically. There are NO GURUs any longer, COP catches them all !
  341.  If you supply a data description file (see below), you even get the
  342.  guru codes in a readable language.
  343.  
  344. VI) How to leave COP
  345. -----------------------------------------------------------------------------
  346.  
  347. Enter GOPG in the COP command line and press RETURN. This should start
  348. the program interrupted.
  349. If you entered COP by a guru, you should first debug the system or will
  350. get just another guru in mostly all cases. There's no good strategy to
  351. accomplish this task....
  352.  
  353. You may also start the old ROMWack from inside COP with the EXIT command.
  354. Starting with ROM versions 3.0, the system debugger has changed to the
  355. (more primitive ? different ?) SAD.
  356. See the autodocs how to use this thing...
  357.  
  358. VII) A word about COP-terminals
  359. -----------------------------------------------------------------------------
  360.  
  361. You will normally use COP's build-in terminal to debug code, but this
  362. terminal will, of course, need some of the hardware systems - the display
  363. system, i.e. the copper and the display DMA channels (not the blitter),
  364. and the keyboard, also the parallel port if you want to print.
  365. I tried to implement the terminal as best as possible, but this may
  366. conflict with other programs which want to use the same hardware resources.
  367. For this reason COP can also be used to debug a system via the serial port.
  368. All you need - for the minimum configuration - is an external
  369. ASCII-terminal,e.g. a second amiga with a standard terminal program will
  370. do it.
  371.  
  372. In this case, choose the following transfer options:
  373.  
  374. 9600 baud, 8 bit, 1 stop bit, no parity
  375.  
  376. no auto CR, no auto LF, nonerasing BS
  377.  
  378.  
  379. However, things are much easier if you use a terminal program providing
  380. COP's private terminal formates, here called type-3 or better terminals.
  381. The terminal transfer standard is documented in the "Terminal.doc" file
  382. in this drawer, if you want to write your own program. There are only
  383. two ready made programs supporting this standard:
  384.  
  385. -THOR's "Terminal" program for all Amigas provides a type-4 terminal
  386.  emulation and is included in this drawer.
  387.  
  388.  Enable the "COP Terminal Emulation" from the menu Settings/Protocol.
  389.  You also need to supply a zero-modem connector, but you should know
  390.  how to build one...
  391.  
  392. -THOR's "DASB" terminal is a full type-4 terminal, working on
  393.  Atari 800XL computers with a serial interface box. It's included
  394.  in the package.
  395.  There are no settings to be made, DASB is written only to communicate
  396.  with COP, but does not support a printer. This drawback arises from the
  397.  Atari XL hardware.
  398.  
  399. If you want to write a COP terminal on your own (e.g for a C64) you
  400. are welcome! Please send me a mail in this case.
  401.  
  402. The build-in terminal for non-remove debugging is of course a full
  403. type-5 terminal.
  404.  
  405. Here, a word about the keyboard processor of the build-in terminal:
  406.  
  407. I tried to write a keyboard parse code not conflicting with other
  408. applications, i.e. it does not read the IRQ-registers of the CIA-
  409. chips and is able to work even with all interrupts disabled. However,
  410. there are "some" drawbacks of this magic stuff : Sometimes a key
  411. may leak thru the keyboard parser to other applications. Because
  412. the corresponding key-up event is missing, the keyboard device will
  413. then activate the auto-repeat loop and generate many key-events.
  414. If this happens, leave COP and press the repeating key to stop it.
  415. Even worse, you wouldn't recognise this bug if the affected key is a 
  416. control key like "Ctrl" or "Shift". If, after leaving COP, the key-
  417. board seems to be out of order, try pressing all this keys first to
  418. send their key-up events. I tried hard to fix this bug, but it looks
  419. like there's no better way to write a magic keyboard parser. If you
  420. want to use COP the professional way, you should work with an external
  421. terminal anyhow.
  422.  
  423.  
  424. VIII) How to enter commands, the line editor
  425. -----------------------------------------------------------------------------
  426.  
  427. Once you've entered COP, it presents you the prompt "COP >" and is ready
  428. to accept debug commands. Below the special keys used for line editing:
  429.  
  430. -The backspace key erases the last character entered and moves the
  431.  cursor backwards one line ("Delete" on some terminal). On some terminals,
  432.  Ctrl-H must be used as a substitution.
  433. -The delete key ("rub-out" on some terminals, Ctrl-Backspace with
  434.  DASB, not available on all terminals) deletes the character under the
  435.  cursor and scrolls the rest of the line backwards
  436. -The return key starts the execution of the command ("Enter" on some
  437.  keyboards)
  438. -Ctrl-C aborts the execution of a command.
  439. -Ctrl-U re-displays the last command entered - there's only a two-line
  440.  history for commands, identical and empty lines will not go to the history.
  441. -The decimal dot on the numeric keypad (for the build-in terminal) or
  442.  the ESC-key on external terminals stops execution of code and enters
  443.  COP. However, this break feature wouldn't work if all interrupts are
  444.  disabled or, if you use the MC68000, the interrupt vectors are messed
  445.  up.
  446. -The cursor-forward-key moves the cursor forward one character (only
  447.  type-3 or higher terminals)
  448. -The cursor-backward-key moves the cursor backwards one character
  449.  (only type-3 and better)
  450. -The cursor-up key moves the cursor to the begin of the line (type-3
  451.  and better only)
  452.  As a replacement, Ctrl-A can be used for this task with TTY-terminals.
  453. -The cursor-down key moves the cursor to the end of the line (type-3
  454.  and better only)
  455.  A replacement for this key is Ctrl-E.
  456. -The Alt-Del key or Ctrl-Clear (with DASB) erases the whole line 
  457.  (type-3 only). This feature is available with Ctrl-B on all ASCII
  458.  terminals.
  459. -The TAB-key has a special meaning while entering data sequences and
  460.  is described below.
  461.  
  462.  
  463. IX) The COP commands and expressions
  464. -----------------------------------------------------------------------------
  465.  
  466. Each COP command looks like the following:
  467. - a four character command base name or a one character abbreviation
  468. - optionally a dot and an extension that determinates a specific
  469.   sub-command of a larger command class
  470. - optionally arguments each separated by space
  471.  
  472. ALL numbers accepted by COP MUST BE GIVEN IN HEXADECIMAL, all arguments
  473. may contain simple calculations with numerical operators. This will be
  474. called an EXPRESSION in the following, abbreviated with <expr>.
  475. Here all supported operators, listed by their priority from low to high
  476. (higher priorities are evaluated FIRST, please note that the priorities
  477.  differ from C!):
  478.  
  479. $               trap operator
  480.                 a$b returns a if b is faulty, else a.
  481.                 NOTE: You cannot enclose $ in brackets, so expressions like
  482.                 (2$a+b)-3 are ILLEGAL !
  483.                 The reason for this is that COP can't continue to evaluate
  484.                 expressions with illegal syntax that will be trapped by $
  485.  
  486. ?,:             C-style condition operator:
  487.                 a?b:c returns b if a is not equal, else c
  488.  
  489. =,<>            equal, not equal: returns -1 if expressions to the
  490.                 right and left are equal (resp. not equal) or 0 otherwise.
  491.  
  492. >,>=,<,<=       signed greater, greater equal, smaller, smaller equal.
  493.                 Returns -1 if the condition is true.
  494.  
  495. |               binary or
  496. !               binary or
  497. ^               binary exclusive or (XOR)
  498. &               binary and
  499.  
  500. +,-             addition, subtraction
  501.  
  502. >>,<<           shift left or right. The left expression is shifted
  503.                 times the right expression
  504.                 
  505. *,/,%           multiplication, integer division, modulo
  506.  
  507. [..]            indirect operator: the value is the (long) content of
  508.                 the address specified by the expression between the
  509.                 braces, e.g. [4] is ExecBase.
  510. [..].l          same as [..]
  511. [..].w          indirect operator, returns the (sign extended) value of 
  512.                 the word at the address in braces
  513. [..].b          indirect operator, returns the (sign extended) value of
  514.                 the byte at the given address
  515. [..].o          the operator size is determinated by the instruction under
  516.                 the program counter.
  517.  
  518.                 NOTE: There is a slight difference if you read a word or a
  519.                 long from an even or odd address. Reading from an even
  520.                 address is only ONE memory access, but reading from an odd
  521.                 one are TWO or FOUR accesses. While not a problem to normal
  522.                 memory, this is a difference for hardware registers !
  523.  
  524. (..)            normal brackets: expression in the brackets is
  525.                 evaluated first
  526. -               unary minus, i.e. change of sign
  527. ~               unary not
  528. >               unary greater. This symbol contains the last address
  529.                 affected by COP and is called the "here" address pointer.
  530.                 It is affected by almost all commands and can be used
  531.                 for saying the new command should "work on the same
  532.                 address" as the last one.
  533. *               unary star. This symbol contains the program counter of
  534.                 the CPU and is equivalent to ".pc"
  535. .b,.w,.l,.o     Sign extension operators. Will interpret the preceding ex-
  536.                 pression as byte, word or long and sign-extend it.
  537.                 So $ff.b is -1, but $ff.w is $000000ff.
  538.                 The .o is again the sign-extension to the operator size
  539.                 of the instruction under the PC.
  540.                 There is a small, but noticeable difference between
  541.                 [adr].b and ([adr]).b ! The first will read only ONE BYTE
  542.                 from memory, the later FOUR BYTES but throwing away three
  543.                 of them. This DOES make a difference if you read a
  544.                 hardware-register !
  545. .reg
  546.  or
  547. 'reg            The content of the CPU register .reg
  548. or              Valid registers are .d0 to .d7 for CPU data registers,
  549. 'reg'           .a0 to .a7 for address registers - note that the
  550.                 meaning of .a7 changes with the supervisor bit -
  551.                 .ssp and .usp for the two stack pointers 
  552.                 .pc (same as *) for program counter and .sr for the
  553.                 status register (there is NO .ccr, use proper masking). 
  554.                 Also, there are 16 COP internal counter registers
  555.                 .c0 to .cf. They are incremented each time they are
  556.                 read and can be used to implement counter breakpoints.
  557.                 For some commands .fp0 to .fp7 are valid and address
  558.                 the eight FPU registers, if a FPU is installed and
  559.                 used by the program debugged.
  560. .sr,.se,.so
  561. .dr,.de,.do
  562.                 These pseudo registers refer to the source and
  563.                 destination effective address of the command under
  564.                 the program counter.
  565.  
  566.                 .sr     is the contents of the source register under
  567.                         the PC, if available
  568.                 .se     is the effective address of the source operand,
  569.                         if available
  570.                 .so     is either the content of the source register or
  571.                         the CONTENT of the effective source address 
  572.                 .dr,.de,.do
  573.                         Same for destination effective address
  574.                 You may alter all these registers to effect the source 
  575.                 or destination operand of an instruction. Although not
  576.                 causing an error, changing .se and .de does nothing
  577.                 usefull.
  578.  
  579.                 Additional, all supervisor registers of the 680x0 series
  580.                 can be viewed, as long as your CPU does support them.
  581.                 In this release of COP, the MMU registers can be changed,
  582.                 but won't be written back...
  583.  
  584.                 A new special register .vvbr has been introduced 
  585.                 in release 1.32:
  586.                 The .vbr register refers always to the VBR of the CPU,
  587.                 but since COP needs this register to operate proberly,
  588.                 you should not change VBR this way. Whenever possible,
  589.                 check the value of VBR, and if it is changed, write
  590.                 the new value not to the VBR, which will confuse COP,
  591.                 but write it to VVBR, and restore VBR to the value of
  592.                 the label COPVBR. COP will then filter out its
  593.                 own exceptions and pass the unused ones back to the
  594.                 system thru VVBR as if the VBR has been set. 
  595.                 The change of VBR will now be detected by COP if the
  596.                 interupt check (ENVI.I) is turned on, and the VBR register
  597.                 can be restored by SETR.V. The autovector table can be
  598.                 rebuild automatically using the IRQ-copyback mode, enabled
  599.                 with the ENVI.C command.
  600.                 
  601. \character      The ASCII-code of the character following
  602.  
  603. $               Unary $. The number following is given in hexadecimal
  604.                 AS THIS IS THE DEFAULT, THIS SYMBOL DOES NOTHING
  605.  
  606. #               The number following is given in decimal, i.e.
  607.                 #16=$10=10
  608.  
  609. %               The next number is a binary number, i.e.
  610.                 %1000=$4=#4=4
  611.  
  612. label           A known label will be evaluated. By default there are
  613.                 only four labels:
  614.                 AbsExecBase     will contain the value 4, thus is
  615.                                 pointing to the pointer of the system
  616.                                 library.
  617.                 Version         Will contain the version of COP as
  618.                                 Version<<16+Revision
  619.                 COPVBR          will contain the interal vector base
  620.                                 setup by COP. VBR should contain this
  621.                                 value.
  622.                                 DO NOT ALTER COP's vector base, use
  623.                                 VVBR instead.
  624.                 COPVVBR         will contain the default position of
  625.                                 COPs virtual vector base.
  626.  
  627.         Some read-only expressions follow:
  628.         (Not starting with a dot -> Not a (pseudo) register -> not alter-
  629.          able !)
  630.  
  631. l0              Left button of mouse or fire on joysticks connected to
  632.                 port 0, returns 0 if released or -1 if pressed
  633. l1              same for port 1
  634.                 l0 and l1 might be quite useful as conditions in
  635.                 breakpoints
  636. r0,r1           Right button of mouse in port 0 or 1
  637. m0,m1           Middle button of mouse in port 0 or 1
  638.         WARNING ! Some hardware limitation cause that it takes max.
  639.         20 msec to read r0,r1,m0,m1. This COULD be made somewhat faster,
  640.         but nevertheless r0,r1,m0,m1 ARE NOT FAST ENOUGH TO BE USED IN
  641.         CONDITIONED BREAKPOINTS.
  642.         This also cause the POTGO-hardware register to be trashed.
  643.         There is no way to save this register back, although
  644.         there is a POTGO-read register - this is a hardware limitation.
  645.  
  646. su,sr   Information about addressing mode under the PC. su and du are
  647. du,dr   TRUE if the source resp. destination operator of the actual
  648.         instruction is used, sr and dr return TRUE if it is a register
  649.         and FALSE if it is in memory.
  650.  
  651. op      Data type of the instruction under the PC, returns
  652.         0 for byte, 1 for word or 2 for long, so 1<<op is the
  653.         size in bytes of the operator.
  654.  
  655. X) List of all commands
  656. -----------------------------------------------------------------------------
  657.  
  658. Long command    Short command   possible extensions     arguments
  659.  
  660. HELP            ?               none                    none
  661.                 prints all COP commands to the active terminal
  662.                 
  663. EXIT            X               none                    none
  664.                 If execbase valid, COP is terminated and the
  665.                 ROMWack is entered. Note that ROMWack works ONLY
  666.                 with an external terminal (if there is one... it
  667.                 has been removed from the 3.1 - V40 roms).
  668.                 
  669. REGS            R               G,E,C,A                 none
  670.                 Register dump commands
  671.                 
  672.                 Without extension:      Dumps all common CPU
  673.                 registers to the screen, dumps fpu registers
  674.                 if FPU is available and in use.
  675.                 
  676.                 REGS.G                  Dumps the guru number
  677.                 and the address that generated the crash. If COP
  678.                 was entered the normal way, the guru number will 
  679.                 be zero.
  680.                 If a data description table was loaded and 
  681.                 gurus were defined, the full name of the
  682.                 guru will be printed.
  683.                 
  684.                 REGS.E                  Dumps special purpose 
  685.                 registers of newer members of the MC68000 family as
  686.                 cache-control and MMU-registers. FPU registers will
  687.                 be included if the FPU is available and in use.
  688.                 
  689.                 REGS.C                  Dumps the COP-internal
  690.                 counter registers (without beeing incremented)
  691.  
  692.                 REGS.A                  Dumps effective address
  693.                 of instruction under PC and memory contents, if
  694.                 available.
  695.  
  696. DUMP            D               B,W,L,C,S,G,H,I,Q,Z,D,X,P,O     <expr>
  697.                 Dump memory. If <expr> is omitted, then the "here"
  698.                 pointer is used as address, otherwise change "here"
  699.                 to the given <expr>.
  700.                 
  701.                 without extension       Dump memory in the last mode
  702.                 used
  703.                 
  704.                 DUMP.B                  dump memory as bytes
  705.                 DUMP.W                  dump memory as words
  706.                 DUMP.L                  dump memory as longs
  707.                 DUMP.G                  dump a sequence of hardware
  708.                                         bytes. The memory manager is
  709.                                         beeing overridden by this.
  710.                                         ! This might be somewhat danger-
  711.                                           ous, if you read some toggle
  712.                                           registers !
  713.                 DUMP.H                  dump hardware word
  714.                 DUMP.I                  dump hardware long
  715.                 DUMP.Q                  dump as quad word (=8 bytes)
  716.                 DUMP.Z                  dump as single precision
  717.                                         IEEE-numbers. 
  718.                 DUMP.D                  dump as IEEE double precision
  719.                 DUMP.X                  dump as MC68881 extended precision
  720.                 DUMP.P                  dump as MC68881 packed decimal
  721.                 DUMP.O                  dump memory as size of instruction
  722.                                         under PC
  723.                 
  724.                 DUMP.C                  Dump memory as characters.
  725.                 All unprintable characters are transcribed with a
  726.                 backslash and the numerical hex value followed.
  727.                 
  728.                 DUMP.S                  Dump memory as strings.
  729.                 All unprintable characters are displayed as a dot.
  730.                 
  731.  
  732.                 After dumping a few lines, COP stops and asks you
  733.                 to press RETURN or SPACE to continue. You may press
  734.                 here Q or Ctrl-C to abort dumping.
  735.                                 
  736.                                 
  737. EDIT            E               B,W,L,C,G,H,I,Z,D,X,P,O         <expr>
  738.                 Edit memory or hardware. If <expr> is omitted, then
  739.                 edit the address given by the "here" pointer. Else
  740.                 use the <expr> as address and save it to "here".
  741.                 
  742.                 In the edit mode, COP presents you the old contents
  743.                 of the address given. This value is now ready to be
  744.                 changed with the edit keys in the last chapter.
  745.                 Press RETURN to accept the changes made or press TAB
  746.                 to undo the changes. Press Ctrl-C to abort editing.
  747.         
  748.         
  749.                 Without extension       use the last edit mode used     
  750.                 EDIT.B                  edit memory as bytes
  751.                 EDIT.W                  edit memory as words
  752.                 EDIT.L                  edit memory as longwords
  753.                 EDIT.Z                  edit as IEEE single precision
  754.                 EDIT.D                  edit as IEEE double precision
  755.                 EDIT.X                  edit as MC68881 extended precision
  756.                 EDIT.P                  edit as MC68881 packed decimal  
  757.                 EDIT.O                  edit memory as size of instruction
  758.                                         under PC
  759.                 
  760.                 EDIT.G                  set hardware as bytes
  761.                 EDIT.H                  set hardware as words
  762.                 EDIT.I                  set hardware as longwords
  763.                 
  764.                 The difference between the first group and the second
  765.                 is that the hardware edit commands do NOT read the
  766.                 hardware registers prior to the user change. Instead,
  767.                 a zero is always beeing displayed. Node that this is
  768.                 necessary cause some hardware registers are WRITE ONLY.
  769.                 In all the modes presented above, you may enter a full
  770.                 <expr> as well as a numeric constant as a new value, 
  771.                 although the length of the <expr> is limited.
  772.  
  773.                 EDIT.C                  edit memory as characters
  774.                 
  775.                 Here, you may edit the memory as ASCII-characters. You
  776.                 may use the backslash followed by a hex number to enter
  777.                 values not available on the keyboard.
  778.                 
  779. EVAL            =               none                    <expr>
  780.                 Evaluate the expression given and print the result.
  781.                 The result might be a simple number, but also very complex
  782.                 expressions including labels are valid.
  783.                 
  784. UNAS            =               none                    <expr>
  785.                 Unassemble code starting with address <expr> and set
  786.                 "here" to this value. If <expr> is missing, disassemble
  787.                 at address contained in "here".
  788.                 
  789.                 The disassembler knows the obcodes of all members of the
  790.                 Motorola MC68000 family, but the non-MC68000 codes are
  791.                 marked. FPU obcodes are disassembled as well, and numerical
  792.         constants will be disassembled as decimal floating point
  793.         expressions.
  794.                 If opcode is illegal, it is marked as well.
  795.  
  796.                 Depending on your enviroment settings - see the ENVI comand
  797.                 - some of the addresses will be expanded to known labels.
  798.                 
  799.                 NOTE: I was unable to test the correct disassembly of the
  800.                 MMU and MC68040 codes, although it SHOULD work.
  801.                 
  802.                 If the address beeing disassembled is the PC, this line
  803.                 is marked with an asterisk *; if it's the "here" pointer,
  804.                 the line is marked with ">".
  805.                 If the address is affected by a break point, a "B" is 
  806.                 inserted.
  807.                 
  808. NODE            N               L                        <expr>
  809.                 Display the node at address <expr>. If <expr> is not
  810.                 present, use the "here" pointer, otherwise set "here" 
  811.                 to the address of the node.
  812.                 
  813.         No extensions        The node's name and its type is 
  814.         displayed.
  815.  
  816.         L            Dump the node as before, but print
  817.         additional information COP can gain about that node. COP
  818.         knowns most node types defined in the Os and will print
  819.         additional information contained in the data attached to 
  820.         the node.
  821.  
  822.                 
  823.                 
  824. LIST            L               M,R,D,I,L,P,T,S,Q,B     <expr>
  825.                 Dump contents of exec-type lists.
  826.                 
  827.                 No extension            Dump the list at given address,
  828.                 set "here" to this address. If <expr> is omitted, use
  829.                 the "here" pointer.
  830.                 
  831.                 B                       Same as without extension, but
  832.                 the list is traversed from the last element to the
  833.                 first. This is sometimes useful if parts of the list
  834.                 are broken.
  835.                 
  836.                 M                       Print exec memory list
  837.                 R                       Print resources
  838.                 D                       Print loaded devices
  839.                 I                       Print software interrupts
  840.                 L                       Print libraries
  841.                 P                       Print ports
  842.                 T                       Print tasks
  843.                 S                       Print semaphores
  844.                 Q                       Print hardware interrupts
  845.                 
  846.                 
  847. FILL            F               M                       <expr>,<expr>
  848.                 Fill memory with byte sequence starting with first <expr>
  849.                 and to last <expr>, exclusive. If one of the <expr> is
  850.                 missing, then "here" is used. Then "here" is set to the
  851.                 first <expr>.
  852.                 
  853.                 without extension       Enter the byte pattern the memory
  854.                 should be filled with. Press TAB to finish one byte, press
  855.                 RETURN to finish the whole sequence and to start filling.
  856.                 
  857.                 M                       Fill memory thru mask (stencil
  858.                 fill operation).        Enter first the byte sequence
  859.                 as described above, then enter the mask bytes. Each
  860.                 bit set to zero in the mask will protect the corresponding
  861.                 memory bit from a change.
  862.                 
  863.                 You may press Ctrl-C anytime to abort the operation.
  864.                 
  865.  
  866. FIND            G               M,I                     <expr>
  867.                 Find byte pattern, masked, or find instruction starting
  868.                 with given address or "here". Set "here" to given
  869.                 expression afterwards.
  870.                 
  871.                 without extension       Enter the byte pattern byte for
  872.                 byte pressing TAB after each byte and RETURN to finish
  873.                 the sequence you are searching for.
  874.                 
  875.                 M                       Find masked memory. Enter first
  876.                 the byte pattern you are searching for and then the mask.
  877.                 Each bit left to zero in the mask will disable the
  878.                 comparision of the corresponding bit in the sequence, i.e.
  879.                 the corresponding bit in the byte pattern will be ignored
  880.                 and will match always.
  881.                 
  882.                 I                       Find instruction. Enter the
  883.                 instruction or part of instruction you want to search
  884.                 for and press RETURN to start the search. Case and extra
  885.                 spaces will be ignored.
  886.                 You should note that all known labels will be expanded
  887.                 by COP unless the enviroment is changed. So you should
  888.                 enter the label-name instead of the address if you look
  889.                 for an access to a defined label !
  890.                 
  891.                 You may press Ctrl-C to abort the searching anytime.
  892.                 
  893.                 
  894.                 
  895. MOVE            M               none                    <expr>,<expr>,<expr>
  896.                 Move source memory block starting with first <expr> and 
  897.                 ending with second argument exclusive to destination
  898.                 given by last <expr>. If any of the <expr> is missing,
  899.                 "here" will be used. Afterwards, "here" is set to the
  900.                 start of the source memory block.
  901.                 Overlapping memory blocks will be handled correctly.
  902.                 
  903.                 
  904.                 
  905. TASK            !               F,W,S                   <expr>
  906.                 Task commands: display,freeze and warm tasks, send
  907.                 signals.
  908.                 
  909.                 without extension       Display information about the task
  910.                 if <expr> is omitted and execbase is valid, the active task
  911.                 will be displayed.
  912.                 
  913.                 F                       Freeze the given task (exclude from
  914.                 execution). If the task to be freezed is the active one,
  915.                 this command will work with Kickstart releases 2.0 or higher
  916.                 only.
  917.                 
  918.                 W                       Warm the given task (include a
  919.                 previously freezed task to task switching).
  920.                 
  921.                 S                       Send signal to a task. You need to
  922.                 supply two arguments, FIRST the signal to be send and
  923.                 SECOND the task affected.
  924.                 
  925.                 
  926.                 
  927. SETR            S               F,E,D,V                  <expr>,reg
  928.                 Set <expr> to given CPU register.
  929.                 
  930.                 without extension       Move given expression to 
  931.                 destination register. Valid destination registers are
  932.                 .d0 to .d7, .a0 and .a7, .ssp,.usp,.pc and .sr, and
  933.                 the COP internal counter registers .c0 to .cf.
  934.                 Note that the meaning of .a7 depends on the supervisor
  935.                 bit in the status register and is identically with
  936.                 .usp or .ssp.
  937.                 Starting with release 1.31, all other CPU supervisor
  938.                 registers can be set as well, but the MMU-registers
  939.                 are not written back (SIGH). 
  940.                 If you need to change the vector basis register VBR
  941.                 of 68010 or above, you should change COP's virtual
  942.                 VBR called .vvbr instead to keep COP's exception
  943.                 vectors untouched.
  944.                 
  945.                 F                       Load FPU register, if FPU is
  946.                 available and in use by the program beeing debugged.
  947.                 In this case, <expr> is a floating point number in the
  948.                 usual notation (e.g. 3.1415 or 3E8 ...).
  949.                 
  950.                 
  951.                 E                       With MC68020 or higher: enable
  952.                 all caches. No arguments need to be supplied.
  953.                 
  954.                 D                       With MC68020 or higher: disable
  955.                 all caches. No arguments taken.
  956.                 
  957.                 V                       With MC68020 or higher: Set the
  958.                 virtual vector base address to VBR, setup VBR to point
  959.                 to COPs interrupt vector table. This command should be
  960.                 given (if it isn't already too late...) if a program
  961.                 changes the VBR to give back control to COP.
  962.  
  963. STEP            Z               none                    <expr>
  964.                 Enter trace mode, start tracing at given address or use
  965.                 PC if <expr> is omitted.
  966.                 How the trace mode works, depends highly on the terminal
  967.                 type used to debug. 
  968.                 On pure ASCII-terminals the command at the PC is beeing
  969.                 disassembled and dumped to the terminal; on type-3 or
  970.                 type-4 terminals however, an entire page of commands
  971.                 is printed. The command at the PC is marked with an
  972.                 asterisk and is beeing highlighted on type-4 terminals.
  973.                 
  974.                 With both types of terminals, COP is now ready to accept
  975.                 one of the following step commands by pressing the
  976.                 desired key:
  977.                 
  978.                 Q or Ctrl-C     Abort trace mode and return to normal
  979.                 command line.
  980.                 
  981.                 S or SPACE      Step the command at the PC. If this is a
  982.                 subroutine call, the subroutine itself will be entered in
  983.                 trace mode and can be stepped thru.
  984.                 
  985.                 T               Trace the next command. The only difference
  986.                 between S and T is how subroutines are handled. With the T
  987.                 command, the subroutine is called as it and will be exe-
  988.                 cuted as whole without beeing stepped thru.
  989.                 
  990.                 N               Next command. Almost like T, but works
  991.                 different with branches. The next command starts the program
  992.                 at the current PC and COP regains control only if the
  993.                 statement IMMEDIATLY FOLLOWING the traced statement is
  994.                 beeing executed. This will be the same as T for all commands
  995.                 but branch and jump commands. You may use N to step thru
  996.                 a loop as whole if you press N for the end condition branch
  997.                 of a loop. 
  998.                 WARNING !!      If this loop has a second exit point, the
  999.                 command after the end condition may never be executed and
  1000.                 COP is never entered again.
  1001.                 WARNING !!      The next command works ONLY IF THE STATE-
  1002.                 MENT IS IN RAM CODE and DOES CHANGE parts of the code by
  1003.                 setting an internal breakpoint. See BRKP-section for a list
  1004.                 of caveats of breakpoints.
  1005.                 
  1006.                 M               Trace until. Almost like T, but the mecanism
  1007.                 how COP regains control after a subroutine call is different.
  1008.                 The 'T' trace changes the return address to COP's entrypoint.
  1009.                 Sometimes this is bad, cause this address might get used
  1010.                 by the called procedure. If you use 'M' instead, the called
  1011.                 procedure will be stepped thru in 'S'-like behaivor using
  1012.                 the CPU's trace-bit. Of course, 'M' will be much slower
  1013.                 and should not be used if some piece of hardware is accessed
  1014.                 or timing is vital.
  1015.  
  1016.                 O               Skip command. Do not execute the command
  1017.                 at the PC and switch PC to the command following.
  1018.                 WARNING !!      Make shure that the command skipped does
  1019.                 not anything important and watch out for side effects,
  1020.                 e.g. skipping a "push long to stack" could be dangerous
  1021.                 if the corresponding stack cleanup command is not skipped
  1022.                 too.
  1023.                 
  1024.                 G               Start program at current PC, activate all
  1025.                 breakpoints.
  1026.                 
  1027.                 R               Dump registers to terminal.
  1028.                 
  1029.                 B               Set breakpoint at current PC address.
  1030.                 Note that commands with a breakpoint on it are marked
  1031.                 with a "B". Further, a breakpoint under the current PC
  1032.                 is "delayed", i.e. that it is not beeing activated until
  1033.                 the PC leaves its address.
  1034.                 The breakpoint set by "B" will be an unconditioned type
  1035.                 (see BRKP for more about breakpoints)
  1036.                 
  1037.                 A               Alter display. If working with the build-
  1038.                 in terminal, the COP display is hidden and the display of
  1039.                 the program is brought to the monitor. The "A" command
  1040.                 is like the "IOCD" command without extension, read this
  1041.                 chapter to find more about COP displays.
  1042.                 If you use the remote-debug feature, this command does
  1043.                 nothing.
  1044.                 
  1045.                 F               Set cop to foreground mode, i.e. COP does
  1046.                 not hide its display if the program beeing debugged re-
  1047.                 gains control. Press F again to activate the normal display
  1048.                 swapping. This command works mostly like the "IOCD.F" 
  1049.                 command, read the "IOCD" section for more information about
  1050.                 COP foreground and background mode.
  1051.                 
  1052.                 
  1053.                 Some caveats about tracing are:
  1054.                 -------------------------------
  1055.  
  1056.                 - COP does not depend on exec-like task switching, it
  1057.                 is NO PROBLEM to step thru exec's task switching procedure.
  1058.                 (This is not a caveat !)
  1059.                 On the one hand a nice feature, on the other hand a problem
  1060.                 if you want to debug a SPECIFIC task. Therefore, you should
  1061.                 trace (T command) over a Wait() or Signal() call of exec-
  1062.                 base. Next (N command) will work too, but if the same code
  1063.                 is used by two tasks - think about the trackdisk code - you
  1064.                 may catch a different task afterwards. Same goes for the
  1065.                 'M' command, but let me remind you again that 'M' is SLOW !
  1066.  
  1067.                 -The second problem with task switching is, that if an exec
  1068.                 task looses control by stepping thru the task-switch 
  1069.                 routine, exec will save its status register with the trace
  1070.                 bit on. If the task is reactivated later, COP will regain
  1071.                 control over this task. While not a problem to COP, this
  1072.                 behaviour might somewhat confusing to you, if COP is
  1073.                 suddenly (probably after hours...) reentered - and not by a
  1074.                 guru.
  1075.                 -There's one extra problem with the trace (T) command :
  1076.                 This commands works by altering the return-address of a
  1077.                 subroutine call. Some programs use this return address to
  1078.                 fetch data following the subroutine call and adjust the
  1079.                 return address afterwards. Cause changed by COP, this
  1080.                 will cause a nice crash of your system. So, if you find
  1081.                 funny code behind a subroutine call, e.g. many illegals
  1082.                 or the like, STEP thru this procedure or use 'M'.
  1083.                 -Since stepping thru a procedure is much slower than
  1084.                 executing one, there may arise timing problems in some
  1085.                 critical IO-procedures. You should trace this kind of
  1086.                 subroutines to avoid such problems. This goes again for
  1087.                 the 'M' command, since this is nothing but "automated
  1088.                 stepping".
  1089.                 
  1090.                 (That looks like a lot of "features" of this debugger,
  1091.                 but they are typically for this class of programs.
  1092.                 However, most authors handle them as "undocumented
  1093.                 features", but I don't. :-) )           
  1094.                 
  1095.                 
  1096. BRKP            B               A,D,C,R,S,O             <expr>
  1097.                 Breakpoint commands. The address affected is given by
  1098.                 <expr> or by "here", if omitted. 
  1099.                 
  1100.                 without extension       If no breakpoint is set at
  1101.                 supplied address, a unconditioned breakpoint is set there.
  1102.                 If a breakpoint is set at this address, the breakpoint
  1103.                 is removed. Note that COP supports up to 32 breakpoints.
  1104.                 It is further important to note that after setting a 
  1105.                 breakpoint, it is not yet active, i.e. causes a COP inter-
  1106.                 cept. The breakpoints are activated each time a program is
  1107.                 restarted, e.g. with the GOPG command; they will get de-
  1108.                 activated each time COP is entered again to prevent an 
  1109.                 endless loop if a breakpoint is set in interrupt code.
  1110.                 However, the breakpoints can be activated by hand, although
  1111.                 this is not recommended.
  1112.                 
  1113.                 
  1114.                 BRKP.A                  Remove all breakpoints (no
  1115.                 arguments accepted)
  1116.                 
  1117.                 BRKP.D                  Display all set breakpoints
  1118.                 with conditions, no arguments accecpted.
  1119.                 
  1120.                 BRKP.C                  Clear breakpoint at given address
  1121.                 
  1122.                 BRKP.R                  Reset all COP counter registers
  1123.                 .c0 to .cf to zero.
  1124.                 
  1125.                 
  1126.                 BRKP.S                  Set breakpoint at given address
  1127.                 and condition, if any. If the condition is omitted, then
  1128.                 an unconditioned breakpoint is set. If a counter
  1129.                 register is included in the condition, it is beeing re-
  1130.                 seted to zero.
  1131.                 With a conditioned breakpoint COP is entered on a BREAK
  1132.                 hit only if the condition is true, i.e. not zero.
  1133.                 You should remember that a counter register is incremented
  1134.                 each time it is accessed, so you may use this feature
  1135.                 to implement counter breakpoints, e.g. ".c0>=5" will stop
  1136.                 execution after the 5th BREAK-hit.
  1137.                 
  1138.                 BRKP.O                  Activate all breakpoints (no 
  1139.                 arguments accepted). Note that this operation might
  1140.                 somewhat dangerous if a breakpoint in an interrupt
  1141.                 procedure gets activated. In this case, COP will display
  1142.                 its "COP crashed" message... have fun.
  1143.                 
  1144.                 Some extra features of breakpoints are the "delay" of
  1145.                 breakpoints and the automatic removal of them:
  1146.                 -If you set a breakpoint under the current PC, this
  1147.                 breakpoint won't get active if you start the program,
  1148.                 but gets activated AFTER the PC leaves the statement. 
  1149.                 This is useful cause you usually never want to break 
  1150.                 on a command you already broke on. You will enter COP 
  1151.                 when the program reaches the breakpoint again.
  1152.                 -If an already activated breakpoint is beeing written
  1153.                 over by a program (e.g. the memory is freed and another
  1154.                 task re-uses this area), this breakpoint is REMOVED
  1155.                 automatically on the time COP is entered again.
  1156.                 This is done to prevent programs from crashing by dangling 
  1157.                 breakpoints of a program that is no longer in memory.
  1158.         
  1159.                 WARNING !       The breakpoint IS NOT removed, if it
  1160.                 is not active at the time it is beeing written over.
  1161.                 This MAY cause problems if the program changes and the
  1162.                 breakpoint is re-activated later, e.g. the breakpoint
  1163.                 may change the address part of a jump-instructions,
  1164.                 possible resulting in a nice fireworks display...
  1165.                 
  1166.                 WARNING !       Active breakpoints change the code
  1167.                 at their address to the ILLEGAL obcode. For this,
  1168.                 BREAKPOINTS DO NOT WORK IN ROM.
  1169.                 Second, if the code is changed, possibly some check-
  1170.                 sums (for libraries or resident code) will change and
  1171.                 things won't work later. For this reason, use the
  1172.                 T S or M STEP subcommands to step thru this part of code,
  1173.                 they DO NOT ALTER the code and work in RAM as well as in
  1174.                 ROM.
  1175.                 
  1176.                 
  1177.                 
  1178.         
  1179. GOPG            G               U,T                     <expr>,<expr>
  1180.  
  1181.                 without extension       Start interrupted program at given 
  1182.                 address or at PC if <expr> is omitted. If any breakpoints
  1183.                 are set, activate them first. A second argument is not
  1184.                 accepted.
  1185.  
  1186.                 U                       Go until
  1187.                 Set a breakpoint at the first given <expr> and start
  1188.                 the program at the address given by the second argument,
  1189.                 or the PC if omitted. Read the breakpoint section about
  1190.                 caveats of breakpoints !
  1191.  
  1192.                 T                       Trace until
  1193.                 Step thru the program until the PC reaches the first
  1194.                 expression. The second expression will be loaded into the
  1195.                 PC if given. This will be very slow, like the 'M' sub-
  1196.         command of STEP.
  1197.                 
  1198.                 
  1199. CAPT            C               S,N,C                     [<expr>,]<expr>
  1200.                 Capture a task, i.e. start debugging it.
  1201.                 
  1202.                 no extension            Capture the task with task
  1203.                 structure at supplied address. If <expr> is omitted,
  1204.                 "here" is used. Afterwards, "here" is set to the
  1205.                 affected task address. If the task uses the FPU,
  1206.                 this capture command will work only with Kickstart
  1207.                 release 2.0 or later, due to the exec private stack frame.
  1208.                 
  1209.                 S                       Like capture without arguments,
  1210.                 but the first argument you supply is a signal mask which
  1211.                 is send to the task before trying to capture it. The 
  1212.                 second argument is the address of the task structure.
  1213.                 
  1214.                 N                       Capture the next task beeing
  1215.                 started. No argument must be supplied with this sub-
  1216.                 command. Note that you might find the new task in the
  1217.                 private dos startup code you have to step thru first.
  1218.                 
  1219.                 C                       Capture next command beeing
  1220.                 started from the shell. This command works only with
  1221.                 Kickstart 2.0 or later.
  1222.                 
  1223.  
  1224.  
  1225. IOCD            O               S,C,B,F,R,Z,L,M,V,P,Q,I,E      <expr>
  1226.  
  1227.                 Input / output commands, terminal commands (rather a
  1228.                 lot of them...)
  1229.                 
  1230.                 without extension       (does not take any arguments)
  1231.                 If you work with COP's build in terminal, toggles between
  1232.                 COP's display and the display of the program beeing de-
  1233.                 bugged. This is not done by intuition or the like, but
  1234.                 by PURE HARDWARE. For this reason, COP need to know the
  1235.                 address of the copper list of this program, and with the
  1236.                 ECS-chipset, the BEAMCON0 value. While both is available
  1237.                 in the graphics library, you must set them by hand if
  1238.                 execbase is destroyed or the program beeing debugged 
  1239.                 uses the hardware register to setup its display.
  1240.                 While COP can almost always establish its screen, it is
  1241.                 sometimes impossible to restore the programs screen
  1242.                 completely - some hardware registers are write-only.
  1243.                 In this case, you MUST use remote-debugging.
  1244.                 If foreground or background mode has been active (see
  1245.                 below) they are deactivated by the IOCD command.
  1246.                 
  1247.                 IOCD.S                  (does not take arguments)
  1248.                 Toggle between build-in terminal and remote-debugging.
  1249.                 If you switch to an external terminal, you should make clear
  1250.                 that this terminal is online, or you might fail to enter
  1251.                 a second IOCD.S to switch back to the build-in one.
  1252.                 Everytime the terinal is changed, COP retries to get the
  1253.                 terminals type to setup type-3 or type-4 communication.
  1254.                 For more information about COP's internal terminal format
  1255.                 and auto-identification read the "Terminal.doc" file
  1256.                 included in this drawer.
  1257.                 
  1258.                 IOCD.C                  <expr>
  1259.                 Set the address of the copper list of the user-program to
  1260.                 re-establish the user's display. If <expr> is omitted,
  1261.                 the "here" pointer is used. You won't need this command if
  1262.                 you debug programs that use the "standard" graphic system,
  1263.                 since COP extracs the address out of gfxbase itself. But
  1264.                 if the user's program uses the hardware registers directly,
  1265.                 COP does not recognize this change of the copper list.
  1266.                 In this case, search with the FIND command for a write to
  1267.                 the hardware register and set this value as user-copperlist
  1268.                 with IOCD.C <expr>. It is seldom easy to find it, so
  1269.                 good luck...
  1270.                 If you have problems with programs using custom copper
  1271.                 lists, you should try the interrupt driven display using
  1272.                 the IOCD.I command (then you get trouble with
  1273.                 interrupts instead of copper lists... ;-)               
  1274.                 
  1275.                 IOCD.I                  (does not take arguments)
  1276.                 Toggle between copper list driven display and interrupt
  1277.                 driven display.
  1278.                 The standard way for COP to display information is to
  1279.                 setup a copper list and to load it into the hardware. Later
  1280.                 on, if the program is started again, the system copperlist,
  1281.                 which can be set by IOCD.C, will be loaded back.
  1282.                 This will, of course, cause trouble if the program changes
  1283.                 the copper list on its own.
  1284.                 The best solution is of course to change to remote de-
  1285.                 bugging using IOCD.S, but startig with release 1.30 COP
  1286.                 can be forced to use a different method of display.
  1287.                 The interrupt driven display does NOT use copper-lists,
  1288.                 but uses the vertical blank interrupt to write the
  1289.                 hardware registers. COP tries its best to keep the programs
  1290.                 setting valid, e.g. if the program disables the interrupt,
  1291.                 COP excludes the user VBI from running. However, this is
  1292.                 really a bit tricky and may fail. A second drawback is,
  1293.                 that the display produced by interrupts is much simpler
  1294.                 and does, for example, not support line highlighting.
  1295.  
  1296.                 IOCD.B                  (does not take arguments)
  1297.                 Set COP to background mode, i.e. COP's display is never
  1298.                 setup and the users display is kept active. However,
  1299.                 you are still ready to enter commands. This mode is
  1300.                 somewhat impracticable since you don't see what you write.
  1301.                 
  1302.                 IOCD.F                  (does not take arguments)
  1303.                 Set COP to background mode, i.e. COP's display is not
  1304.                 removed from the monitor (only execption: a GOPG command
  1305.                 or the G subcommand of the STEP-command). Use this command
  1306.                 to avoid that flicker, that occurs if the screen changes.
  1307.                 There's one caveat with this command and the STEP-command:
  1308.                 Since the displays are not swapped, the user program may 
  1309.                 destroy COP's display by writing to a hardware register or
  1310.                 may get unexepected results reading a register while COP's
  1311.                 display is active.
  1312.                 So watch out and disable the foreground mode if you want
  1313.                 to step this type of commands.
  1314.                 
  1315.                 IOCD.R                  (does not take arguments)
  1316.                 Disables foreground and background mode and restores
  1317.                 normal display swapping.
  1318.                 
  1319.                 IOCD.Z                  <expr>
  1320.                 Set the screen size of the build-in terminal to <expr>
  1321.                 lines. If <expr> is omitted, the actual display size
  1322.                 will be used.
  1323.                 The standard screen size is 28 (=$1C, remember COP always
  1324.                 thinks in HEXADECIMAL !) lines, but this might be to
  1325.                 large for some monitors. To prevent you grabbling at your
  1326.                 monitor, this command can be used to setup a fitting
  1327.                 display size. However, the screensize is limited to 8 to
  1328.                 28 lines and will always be centered.
  1329.                 
  1330.                 IOCD.L                  <expr>
  1331.                 Setup the number of lines until COP presents its ***more***
  1332.                 message to ask for continue. This number is more an 
  1333.                 approximate value as some outputs can't be broken up into
  1334.                 lines (for example the register display does never generate
  1335.                 a ***more*** message).
  1336.                 If <expr> is not given, the command uses the last value.
  1337.                 (Remember that COP thinks in HEX, so 10 is not TEN but
  1338.                 SIXTEEN !)
  1339.                 
  1340.                 
  1341.                 IOCD.M                  <expr>
  1342.                 Set the value to be written to BEAMCON0 if user display
  1343.                 should be rebuild. This command is not necessary until
  1344.                 an application uses the hardware registers directly.
  1345.                 See IOCD.C and IOCD for more information about this
  1346.                 feature.
  1347.                 If possible, COP tries to build a NTSC-display, cause
  1348.                 it is less flickering than a PAL screen. I think there
  1349.                 should be no problems with this feature, even commodore's
  1350.                 @#!?!-monitor does support 60Hz displays and most european 
  1351.                 TVs will do so too. If there are problems, use the next
  1352.         option to use a PAL display instead, or use the PAL
  1353.         command line option (see below).
  1354.  
  1355.         IOCD.V            (does not take arguments)
  1356.         Toggles between PAL and NTSC display, if possible (ECS or
  1357.         better is required for this function)
  1358.                 
  1359.                 IOCD.P                  (does not take arguments)
  1360.                 Toggles printer output.
  1361.  
  1362.                 Not all commands cause a printer output, e.g. the edit
  1363.                 and step commands do not, since they are interactive.
  1364.  
  1365.         
  1366.                 IOCD.Q                  (does not take arguments)
  1367.                 Toggles printer support via the build-in printer driver
  1368.                 thru the parallel port of the amiga or the terminal
  1369.                 connected to COP (this is the default).
  1370.                 If you use the build-in terminal emulation, this command
  1371.                 will make no difference at all, but with an external type-5
  1372.                 terminal COP will either print itself or tell the external
  1373.                 terminal to start or stop printing. The later method is of
  1374.                 course the better one, it does not take over the parallel
  1375.                 port hardware.
  1376.  
  1377.                 All IO-commands but the L,S,P and Q subcommand don't make
  1378.                 sense in a remote-debug session and don't do anything in 
  1379.                 this case.
  1380.  
  1381.         IOCD.E            (does not take arguments)
  1382.  
  1383.         This command does not take any arguments. It will send a 
  1384.         FORM FEED control character to the connected printer, to
  1385.         eject the paper. This might be needed by some laser or
  1386.         deskjet printers.
  1387.  
  1388.  
  1389. ENVI            V                       R,L,I,B,X,E,M,F,D,C    <expr>
  1390.                 Enviroment settings, mode settings and so on.
  1391.                 
  1392.                 without extension       Not valid. This command MUST
  1393.                 be extended.
  1394.                 
  1395.                 ENVI.R                  (does not take arguments)
  1396.                 Enter raw mode. In this mode,
  1397.                 execbase is not used at all. There are much consequences
  1398.                 of entering the raw mode: The display copper list and
  1399.                 beamcon0 must be set by hand (with IOCD.C and IOCD.M),
  1400.                 interrupts are disabled if COP is entered, all list
  1401.                 commands depending on exec-lists, all task commands and
  1402.                 all capture commands refuse to work. The EXIT command
  1403.                 is not available, too.
  1404.                 There is no message if these commands are still entered.
  1405.  
  1406.                 All exceptions except interrupts cause now COP to inter-
  1407.                 cept, even if there is an exception handler installed in
  1408.                 the active task - normally it's no problem to run COP
  1409.                 parallel to a "normal" debugger, but in RAW-mode COP will
  1410.                 capture even its breakpoints.
  1411.                 
  1412.                 If you've entered the raw mode once, there's NO WAY
  1413.                 TO SWITCH IT OFF LATER except a power up, so be careful !
  1414.                 
  1415.                 You should use the raw mode if you MUST debug a program
  1416.                 that uses the hardware directly. In most cases, it is
  1417.                 necessary to use remote debugging too.
  1418.  
  1419.                 If you must use the chip-mem buffer, you are REQUESTED TO
  1420.                 USE the raw mode too, or you will run into BIG TROUBLE
  1421.                 with task switching activity.
  1422.                                 
  1423.  
  1424.  
  1425.                 ENVI.L                  <expr> <expr>
  1426.                 Add memory section. Cause COP does not use the exec
  1427.                 memory list, COP tries to find the memory portions
  1428.                 in your system on startup, i.e. chip mem, fast mem
  1429.                 and the kickstart ROM. However, COP cannot handle 
  1430.                 "too complicate" memory models, e.g. fast mem that
  1431.                 is split in several blocks or memory that is not
  1432.                 aligned to 64K borders.
  1433.                 To fit your needs, you may add a memory chunk of
  1434.                 your choice to COP's list.
  1435.                 The first argument specifies the start address of
  1436.                 the block, the second the (exclusive) end address,
  1437.                 if both are equal, this memory block will be removed 
  1438.                 from COP's private list.
  1439.                 
  1440.                 This memory list is used for the FIND and FILL commands,
  1441.                 memory is beeing scanned for all addresses in it.
  1442.  
  1443.                 NOTE:           Normally, the memory in an Amiga is
  1444.                 typically not organized in a linear way, some memory parts 
  1445.                 are mirrored to others and the memory is possibly split
  1446.                 into some chunks, e.g. if you have a memory expansion
  1447.                 card in an old Amiga 2000B with ranger-memory (slowmem).
  1448.                 In this case, your fast mem will fill the addresses
  1449.                 0x00020000 to ? and 0x000c8000 to 0x000d0000. In this 
  1450.                 case COP will search the total area from 0x00020000 to 
  1451.                 0x00d00000, including some hardware registers in between.
  1452.                 In this release, COP can not handle such complicated memory
  1453.                 models, maybe later...
  1454.                 (This is even better than pre-1.17 releases, which were un-
  1455.                 able to work with A4000 memory models....)
  1456.                                                 
  1457.                 ENVI.I                  (no arguments)
  1458.                 Disable the checking of changes of IRQ-vectors.
  1459.                 Under normal conditions, COP checks the consistency of
  1460.                 the MC68000 autovector table, used by COP to allow trace and
  1461.                 breakpoint commands. If one of the entries are changed,
  1462.                 you will be prompted by a message if it's O.K. to undo the
  1463.                 change, to accept it (in this case COP writes the change
  1464.                 back to its second vector table, which can be used by
  1465.                 ENVI.F), or to ignore one or all changes.
  1466.  
  1467.                 This change could be done by a faulty program, or
  1468.                 by a program that wants to regain control over the whole
  1469.                 system. In the first case it's better to answer U(ndo), in
  1470.                 the later C(hange). If you use a MC68000, the address in the
  1471.                 trace and illegal trap vectors are vital, and any change
  1472.                 of them will prevent COP from beeing able to step thru
  1473.                 programs. Also, COP needs at least one interrupt that
  1474.                 occurs "often enough" to check the status of the break key.
  1475.                 With a MC68010 or higher things are not that worse, cause
  1476.                 COP uses the VBR register to move the autovector table
  1477.                 to a different part of the memory. However, changes to
  1478.                 the old table will be respected, although COP does not yet
  1479.                 notice the change of the VBR register. In a case you notice
  1480.                 that the VBR has been changed, set it back to the old
  1481.                 value which can be found in the label COPVBR and place the
  1482.                 new value in the virtual vector base called VVBR.
  1483.  
  1484.                 If you disable the IRQ-checking, all changes to the
  1485.                 autovector table are ignored.
  1486.  
  1487.                 ENVI.C                  (no arguments)
  1488.                 Enables the IRQ copy back mode.
  1489.                 Instead of watching the low-memory vector base, COP keeps
  1490.                 an eye on its own vector offset and copies the changed
  1491.                 vectors on request to the virtual vector base. This option
  1492.                 should be choosen if you want to debug a program that
  1493.                 directly writes to the vector base, like ShapeShifter.
  1494.                 The command line option "MacMode" enables this automatically.
  1495.                 Be warned: Enabling the copy back mode disables the check
  1496.                 for the low memory vector table, which normally used be the
  1497.                 amiga OS.
  1498.                 This check can be disabled with the ENVI.I switch described
  1499.                 above and works of course only for the mc68010 or better.
  1500.  
  1501.               
  1502.                 ENVI.B                  (no arguments)
  1503.                 Toggles the ChipMem backsave buffer.
  1504.                 The display build up by COP's internal terminal emulation
  1505.                 needs some chip memory that might be occupied by the
  1506.                 program you want to debug. If you want to prevent COP
  1507.                 from overwriting this area, you must:
  1508.                 o) provide a backsave area using the BUFFER keyword on
  1509.                    the command line when COP is installed
  1510.                    (usually in the startup-sequence)
  1511.                 o) enter the ENVI.B command to enable this buffer
  1512.                 o) you SHOULD use the Raw-mode to prevent conflicts with
  1513.                    multitasking
  1514.  
  1515.                 If the buffer is enabled, COP will backup the occupied 
  1516.                 memory area each time it builds its own display and will
  1517.                 restore it, if the program's display is restored later.
  1518.                 However, this backup mechanism is not (yet) fully trans-
  1519.                 parent to other parts of COP, but the UNAS and DUMP
  1520.                 commands keep care. It will therefor be convienent to 
  1521.                 place COP's CHIP hunk an uninteressting part of memory,
  1522.                 e.g. the display buffer of the debugged program would be
  1523.                 fine. To prevent problems with the blitter, COP will wait
  1524.                 for the blitter beeing finished before swapping the memory.
  1525.                 In all other cases the blitter will just be stopped.
  1526.  
  1527.                 ENVI.X                  (no arguments)
  1528.                 Affects the way the disassembler handles the indexed
  1529.                 indirect mode with label generation. The default is, that
  1530.                 the address which is used for label generation is given
  1531.                 by the base register plus the index. This is most com-
  1532.                 fortable if, for example, all entries of an indexed table
  1533.                 have labels associated to them. If, however, you want to
  1534.                 reassemble a part of code, this would be fatal since
  1535.                 all assemblers calculate the displacement, which will
  1536.                 be replaced by the label, as a distance to the base
  1537.                 register without the index. So if you switch out the
  1538.                 index inclusion, you will only see labels associated
  1539.                 to the base of a indexed table.
  1540.  
  1541.                 ENVI.E                  (no arguments)
  1542.                 Toggle the label generation. If you do not want to see
  1543.                 labels, for example in a search process looking for a
  1544.                 instruction with specific address, you can switch out
  1545.                 the label generation at all using ENVI.E
  1546.  
  1547.                 ENVI.M                  (no argument)
  1548.                 Toggle the build-in memory manager. This part of code
  1549.                 in COP protects you from writing into hardware and non-
  1550.                 existing memory, as well as it does the memory re-
  1551.                 mapping for the chipmem-buffer. If, for special purposes,
  1552.                 you want to disable this feature, use ENVI.M
  1553.  
  1554.                 ENVI.F                  (no argument)
  1555.                 Toggle the place where the exception vectors are stored.
  1556.                 The default location is at address 0, but since this is
  1557.                 chip memory, exception handling gets slow. If you use
  1558.                 ENVI.F, the vector base will be located in the fast-memory.
  1559.  
  1560.                 Warning ! ENVI.F does NOT change the vector base register
  1561.                 at all, since it is pointing to COP's own vector base at
  1562.                 any time. Instead, it says COP where to look for the system
  1563.                 vectors, so changes only the virtual vector base VVBR.
  1564.                 Warning ! ENVI.F will overwrite the virtual vector base
  1565.                 register VVBR of COP in order to work ! So do not use this
  1566.                 command if you setup your own VVBR.
  1567.  
  1568.                 This command only takes effect if running under a MC68010
  1569.                 or better, since the plain MC68000 does not have a VBR.
  1570.  
  1571.  
  1572.                 ENVI.D                  (no argument)
  1573.                 Toggle the default input radix, with is set up as hex,
  1574.                 to decimal and back.
  1575.  
  1576. SPLT            /               C               <expr>
  1577.                 This command is available ONLY if you use the build-in
  1578.                 terminal or an external type-3 or type-4 terminal. It
  1579.                 won't work with a raw ASCII-terminal.
  1580.                 
  1581.                 COP has the ability to split of a part of the screen for
  1582.                 displaying some information permantly. This information
  1583.                 in then updated each time you enter a command or COP
  1584.                 looses or regains control over the system. For example,
  1585.                 splitting the screen and displaying the register set in
  1586.                 the upper part of the screen while tracing is highly use-
  1587.                 ful and is nowadays standard for all debuggers.
  1588.                 Cause COP is "a little" different from that ones, you
  1589.                 must enable this feature, and due to the raw display
  1590.                 system, it's not available in general - a raw ASCII
  1591.                 terminal can't split the screen.
  1592.                 
  1593.                 without extension       COP displays a new prompt and you
  1594.                 should enter a command that shall be executed each time
  1595.                 the display must be updated. The output of this command is
  1596.                 then displayed in a separated part of the display.
  1597.                 It is possible to execute more than one command if you
  1598.                 separate all commands by colons.
  1599.                 The argument following the SPLT-command determinates the
  1600.                 approximate size of the split-off part of the display 
  1601.                 (in lines; remember that all numerical values are HEX-
  1602.                 VALUES by default !). If there's not enough room, not
  1603.                 all commands will be executed.
  1604.                 
  1605.                 There are a few caveats to remember when using the SPLT-
  1606.                 command:
  1607.                 -Not all commands are splitable, e.g. the SPLT and the
  1608.                 STEP commands.
  1609.                 -Some commands are splitable, but it's not very useful
  1610.                 to split them, cause they get executed each time the
  1611.                 display is updated, e.g. the GOPG and the EXIT commands.
  1612.                 -Almost all commands change the "here"-pointer. This is
  1613.                 NOT true for commands executed in the split-window, i.e.
  1614.                 they can READ "here", but do not change them.
  1615.                 This is somewhat useful since, while tracing, the "here"
  1616.                 pointer contains the address of the first command of the
  1617.                 lower window, e.g. splitting the command "d.w" will dump
  1618.                 the obcodes of the program in hex.
  1619.                 
  1620.                 Some useful commands for splitting:
  1621.                 REGS            will present a auto-updating register dump
  1622.                 NODE .a6        will print the name of the library pointed
  1623.                                 to by a6
  1624.                 DUMP.L .a0      will dump the memory pointed to by a0.
  1625.                                 (display will change if a0 changes, of
  1626.                                 course)
  1627.                 
  1628.                 (Remeber that you need to supply a dot in front of the
  1629.                 register names to distinguish between registers and
  1630.                 addresses)
  1631.                 
  1632.                                 
  1633.                 Remember that you can execute more than one command once,
  1634.                 e.g. REGS:NODE .a6
  1635.                 
  1636.                 
  1637.                 SPLT.C                  (no arguments accepted)
  1638.                 Remove the split window and return to normal operation.
  1639.                 
  1640. SKTB            T               <expr>
  1641.                 Stack traceback.
  1642.  
  1643.                 Search the stack at the given address or at the address
  1644.                 given by the active stack pointer for data- and
  1645.                 code addresses. This will be useful if you want to find
  1646.                 out, which part of code called a faulty procedure.
  1647.  
  1648.                 COP TRIES to find out if the data on the stack is
  1649.                 yust garbage (which won't be printed) or a pointer
  1650.                 to data, or a returnaddress to a piece of code.
  1651.  
  1652. LABS        A            E,S,B,G,T,V,A,U,L    [name]
  1653.         Dump labels.
  1654.  
  1655.         This command prints informations about label definitions
  1656.         loaded into COP. A line dumped by this command will look
  1657.         like the following:
  1658.  
  1659. label name    :    value    (+ base)        (flags)
  1660.  
  1661.         Some labels are either relative to a base, which is printed
  1662.         in hex if so, or relative to an exec node. It's name is
  1663.         printed if so.
  1664.  
  1665.         The characters in the brackets specify the type of the 
  1666.         label:
  1667.  
  1668.         A    absolute address
  1669.         E    equate. An easy to remember expression representing
  1670.             a number.
  1671.         N    an address relative to a node, thus, an offset.
  1672.         V    a function vector of a library or a device.
  1673.         R    an offset relative to a absolute base.
  1674.         S    a size of something. Currently not supported.
  1675.         B    a bit definition.
  1676.         L    A lineA trap definition (not required by the
  1677.             Amiga-OS, but by the Mac OS)
  1678.  
  1679.         s    A COP internal (system) label. There are currently
  1680.             only four system labels.
  1681.         r    A read-only label.
  1682.         k    A resident label, can't be removed with FLUSHALL
  1683.         t    A temporary (so, user) label. Can be removed with
  1684.             FLUSH.
  1685.  
  1686.  
  1687.         The "name" argument specifies the label you'd like to know
  1688.         information about. Wildcars are welcome here, COP knows
  1689.         only two wildcards, '?' for one unknown character and '*'
  1690.         for a sequence of unknown characters. If you don't give a
  1691.         name, COP selects "*" for you as default, i.e. will show
  1692.         all label.
  1693.  
  1694.         The extensions specify the type of labels in the list:
  1695.  
  1696.         
  1697.         LABS.E            [name]
  1698.         Dump equates only.
  1699.  
  1700.         LABS.S            [name]
  1701.         Dump only sizes.
  1702.  
  1703.         LABS.B            [name]
  1704.         Dump bit definitions.
  1705.  
  1706.         LABS.G            [name]
  1707.         Dump guru's.
  1708.  
  1709.         LABS.T            [name]
  1710.         Dump line-A traps.
  1711.  
  1712.         LABS.V            [name]
  1713.         Print function vectors.
  1714.  
  1715.         LABS.A            [name]
  1716.         Print addresses. Absolute, relative or node relative.
  1717.  
  1718.         LABS.U            [name]
  1719.         Print all user defined (temporary) definitions.
  1720.  
  1721.         LABS.L            [name]
  1722.         Print all definitions.
  1723.  
  1724.         LABS            [name]
  1725.         Print all user defined addresses.
  1726.         
  1727.  
  1728.                 
  1729. XI) COP arguments to the command line and ToolTypes for the Workbench
  1730. ---------------------------------------------------------------------
  1731.  
  1732. Here a list of arguments COP acceptes as arguments when getting started
  1733. from the shell. However, it's possible to start COP from the workbench
  1734. and to supply the same arguments as tooltypes. Create simply for each
  1735. argument a tooltype of the same name.
  1736.  
  1737. KEYMAP  <keymap>        Set the keymap COP should use for the build-in
  1738. terminal. Please note that you CAN NOT change this keymap with the
  1739. SetMap or SetKeyboard command. This keymap is of course not used for
  1740. remote debugging.
  1741. The keymap file is searched in the DEVS:keymaps drawer (not in KEYMAPS:
  1742. cause this logical device is not standard with Kickstart 1.2 or 1.3)
  1743. or in the keymap.resource. You need to supply AT LEAST AT STARTUP
  1744. a KEYMAP argument to define the keymap COP shall use. (There's no default
  1745. in this release, a missing keymap argument will result in an unusable
  1746. build-in terminal)
  1747.  
  1748.  
  1749. SERIAL                  Choose remote debugging
  1750. DISPLAY                 Choose build-in terminal for debugging
  1751. Note that you MUST supply the DISPLAY argument if you want to enter COP
  1752. by a shell command or COP will switch to remote-debugging.
  1753.  
  1754.  
  1755. LINES <number>          Set the number of lines of the build-in terminal
  1756. screen, the default is 28. This argument will be ignored if COP is already
  1757. loaded, use the IOCD.Z command instead.
  1758.  
  1759. BREAKKEY <number>       Set the keycode (NOT the ASCII-value !) of the
  1760.                         BREAK-key. This value will be used only by the
  1761.                         internal terminal emulation and will be ignored
  1762.                         under remote debugging.
  1763.                         Some useable keys (in other words: You
  1764.                         MAY use the return key, but...) are:
  1765.                         93      the asterisk on the numeric key pad
  1766.                         90      the braket-left key on the pad
  1767.                         91      the braket-right key nearby
  1768.                         74      the minus key on the pad
  1769.                         94      the plus key underwards
  1770.                         60      the dot on the key pat
  1771.                                 this is the DEFAULT.
  1772.                         
  1773.                         You may also use hex numbers if you place a $ or a
  1774.                         0x in front of them.
  1775.                                                 
  1776. RESIDENT                Load COP resident into memory, i.e. COP will survive
  1777. a reset if execbase is still o.k. and need not to be reloaded. This option
  1778. is useful if you want to debug startup-code.
  1779.  
  1780. REMRESIDENT             Remove COP from the resident list and free all its
  1781. memory. Cause COP can not be removed completely, RESTART YOUR COMPUTER
  1782. IMMEDIATLY AFTER EXECUTING THIS COMMAND. Some code may write over COP's
  1783. still installed interrupt code resulting in a fireworks display or a crashed
  1784. harddisk (oh what a fun...).
  1785.  
  1786.  
  1787. GO                      Start a debug session using COP.
  1788.  
  1789. BUILDINPRT              Use the build-in printer support thru the parallel
  1790. port of the Amiga instead of the external terminal printer support. This
  1791. option works like the IOCD.Q command.
  1792.  
  1793. TERMINALPRT             The counterpart of BUILDINPRT: Use the printer pro-
  1794. vided by the terminal connected to COP. If you choose the build-in terminal
  1795. emulation, this won't make any difference. However, if you debug with an ex-
  1796. ternal terminal, the printing will be done thru its port and not thru the
  1797. amiga parallel port.
  1798.  
  1799.  
  1800. IRQDISPLAY              Select the buildin-terminal emulation, switch to
  1801. interrupt driven display. This acts like the IOCD.I command.
  1802.  
  1803. COPPERDISPLAY           Select the copper driven display as default.
  1804.  
  1805.  
  1806. IRQCOPYBACK             Select the IRQ copyback mode: COP does not watch the
  1807. low-memory interrupt vector table, but its own vector table and will copy
  1808. changes to the virtual vector base. This is the command-line counterpart of
  1809. the ENVI.C setting.
  1810.  
  1811. NOIRQCOPYBACK           The default operation of COP: Watch the standard
  1812. interrupt vector table, which is located at address 0 and up. Both checks
  1813. can be disabled with the ENVI.I switch.
  1814.  
  1815. MACMODE                 This macro switch enabled some options and settings
  1816. required for COP to run safely under the shapeshifter Macintosh emulator.
  1817.  
  1818. SET60                   Say COP that a MC68060 processor is in your system,
  1819. although exec.library does not know. The standard Amiga OS 3.1 does NOT
  1820. recognize a '60 processor, the correct flags are usually setup later by
  1821. a tool provided by the hardware manufacturer. If you want to run COP
  1822. prior to these tools, specify the SET60 option.
  1823. This flag DOES NOT change the processor flags in the exec.library!
  1824.  
  1825.  
  1826. The next two options contol the video mode used by COP for its own display:
  1827.  
  1828. NTSC            Use a NTSC screen for the debugger screen. This has
  1829.             been the default for versions up to 1.56.
  1830.  
  1831. PAL            Use a PAL screen instead. This is, however, more
  1832.             flickering.
  1833.  
  1834. Now some options that tell COP where to place itself in memory. They do
  1835. not work if COP is already loaded !
  1836.  
  1837. CODE where              Tell COP where to place its CODE segment. where
  1838. might be:
  1839.         FORWARD         Allocate memory from the beginning of the memory
  1840.                         area, so COP is placed at LOW addresses.
  1841.                         This is impractical in most cases.
  1842.  
  1843.         REVERSE         Allocate memory from the end of the memory, so
  1844.                         COP is placed at HIGH addresses. This was the
  1845.                         default up to release 1.18.
  1846.  
  1847.         address         Place COP at an absolute address, given in decimal
  1848.                         or in hex if preceded by $ or 0x.
  1849.                         This memory area must be available, as long as you
  1850.                         do not use the FORCE option.
  1851.  
  1852. DATA where              Tell COP where to place the DATA section. The 
  1853.                         argument is the same as above.
  1854.  
  1855. BSS  where              ...same for BSS section
  1856.  
  1857. CHIP where              ...same for CHIP section. If you use an absolute
  1858.                         address here, make shure it is in chip mem !
  1859.  
  1860. LABEL where             ...same for LABEL section, which is needed if
  1861.                         you give a DDT (see below) and containes 
  1862.                         the names and addresses of DDT labels.
  1863.  
  1864. BUFFER where            Tell COP to use a chip-memory backup buffer and
  1865.                         place it according to the argument. You MUST
  1866.                         provide this argument if you want a chipmem backup
  1867.                         area, or the ENVI.B command won't work.
  1868.  
  1869. RESIDENTSTRUCT where    Tell COP where to place the resident structure that
  1870.                         is needed for COP to keep resident over resets.
  1871.                         This argument is only useful if you use the
  1872.                         RESIDENT switch too.
  1873.  
  1874. FORCE                   Tell COP to use the specified memory, even if it is
  1875.                         occupied by another program. WARNING !
  1876.                         YOU SHOULD BE REALLY SHURE WHAT YOU ARE DOING if
  1877.                         you MUST use this option ! Portions of code of
  1878.                         other programs might get overwritten by COP, causing
  1879.                         a fantastic crash !
  1880.  
  1881. FLUSH                   Flush labels loaded as symbols from a segment,
  1882.                         e.g. loaded by CLIDEBUG or WBDEBUG.
  1883.                         This is done automatically every time if you
  1884.                         specify CLIDEBUG or WBDEBUG.
  1885.                         However, the labels defined in the DDT file
  1886.                         are left alone.
  1887.  
  1888. FLUSHALL                Flush all labels, even those defined in a
  1889.                         DDT file. The system labels AbsExecBase, Version
  1890.                         COPVBR and COPVVBR survive.
  1891.  
  1892. CLIDEBUG                Debug a program using the Shell interface. If
  1893.                         you want to give arguments to the program to
  1894.                         debug, INCLUDE THE COMMAND AND ITS ARGUMENTS
  1895.                         by double qoutes. Since a colon and an asterisk
  1896.                         is interpreted by COP as the beginning of a
  1897.                         comment, you MUST enclose these characters
  1898.                         in an additional pair of single quotes.
  1899.                         To simplify this, you might use the DEBUG
  1900.                         script.
  1901.                         CLIDEBUG always flushes the labels.
  1902.  
  1903. WBDEBUG                 Debug a program thru the workbench interface.
  1904.                         If you want to support a second icon which is
  1905.                         simulated to be clicked with the main program's
  1906.                         enclose THE MAIN AND THE SECOND ARGUMENT IN
  1907.                         DOUBLE QUOTES. DO NOT ADD ANY .INFO TO THE
  1908.                         NAME, even if you load an icon of project type.
  1909.                         The responsible program will be found and be
  1910.                         loaded.
  1911.                         WBDEBUG always flushes the labels.
  1912.  
  1913. SYMBOL                  Add the symbols of the given binary file to
  1914.                         the label buffer. To do so, you MUST support
  1915.                         the base address of the segment using
  1916.                         SEGMENT or FIRSTHUNK.
  1917.                         Adding of additional labels might be necessary
  1918.                         if you debug an overlayed program. COP cannot
  1919.                         load all labels on startup, since it is not clear
  1920.                         where the overlay nodes will be placed in memory.
  1921.                         Remember the base address of the program if loaded;
  1922.                         Later on, if the overlay nodes are present, reload 
  1923.                         the symbol table by FLUSH SYMBOL <progname>
  1924.                         FIRSTHUNK addr. 
  1925.                         The FLUSH should be added to avoid adding the labels
  1926.                         twice. Though possible, this is a waste of memory.
  1927.  
  1928. FIRSTHUNK               Give the APTR to the first byte of the first hunk
  1929.                         to which the labels to be loaded belong.
  1930.                         Either FIRSTHUNK or SEGMENT MUST BE USED as an
  1931.                         additional argument if you use SYMBOL.
  1932.  
  1933. SEGMENT                 Give the BPTR, as available from LoadSeg(),
  1934.                         of the segment to which the labels to be loaded
  1935.                         by SYMBOL belong.
  1936.                         Either this or FIRSTHUNK IS NECESSARY with SYMBOL.
  1937.  
  1938. CALC                    Calculate the expression given. Everything COP's
  1939.                         EVAL command can evaluate is valid here, even
  1940.                         defined labels. So to read the value of ExecBase
  1941.                         using the Shell is quite easy:
  1942.                         COP CALC [AbsExecBase]
  1943.                         Note that this allows using COP as a symbol data-
  1944.                         base, e.g. to remember the system entry points.
  1945.                         COP CALC OpenLibrary
  1946.                         will give the offset of the OpenLibrary system
  1947.                         call, provided you added it using a DDT.
  1948.                         The only caveat is that COP will assume all
  1949.                         numbers are in decimal unless preceeded by $.           or $, independend of the radix switch.
  1950.                         The $ notation, however, may conflict with
  1951.                         shell variables, so enclose the argument, also
  1952.                         if it contains spaces, in double quotes.
  1953.  
  1954.  
  1955. If you want to build an icon to start COP from the workbench, use for
  1956. example the following tooltypes:
  1957.  
  1958. DISPLAY                 MUST be present to prevent COP from remote-
  1959.                         debugging mode.
  1960. GO                      MUST be present if you want to start COP.
  1961.  
  1962.  
  1963. DDT file                Setup COP's labels using a data description
  1964.                         table. The syntax of this file is descripted
  1965.                         below, and a default table "startup.ddt" is
  1966.                         included in this drawer. If you want to run COP
  1967.                         together with the macintosh emulator, you should
  1968.                         specify the macintosh-version of the ddt file
  1969.                         called MAC.ddt and the MACMODE command line
  1970.                         switch.
  1971.  
  1972.                         You should use this option in your startup-
  1973.                         sequence to load all default labels.
  1974.  
  1975.                         It is fine to call COP again with this option
  1976.                         if you want to add some labels, however, if you want
  1977.                         to reload the table, you should flush all the
  1978.                         old labels with the FLUSHALL option.
  1979.  
  1980.  
  1981. Of course, if COP is already present, the code loaded will get started and
  1982. will not be loaded again (and therefore, some options are useless in this
  1983. case !)
  1984.  
  1985. If you want to debug a Shell program, this command line would be nice:
  1986.  
  1987. COP CLIDEBUG "c:copy s:Startup-Sequence to '*'"
  1988.  
  1989. will debug the copy command in copying the startup-sequence to the console.
  1990. Please note the necessary quotes around the command line and the star.
  1991.  
  1992.  
  1993. To debug a Workbench progam, say the Shell-Icon, type:
  1994.  
  1995. COP WBDEBUG "SYS:Shell"
  1996.  
  1997.  
  1998. Debugging overlayed programs is a bit tricky. First load the program
  1999. itself, e.g. with
  2000.  
  2001. COP CLIDEBUG "overlaydemo"
  2002.  
  2003. Now write down the address of the breakpoint when COP is entered.
  2004. Step thru the code until a new overlay segment is loaded. To do so,
  2005. set a breakpoint in the overlay manager, which will always be the first
  2006. hunk of the program. Then, load the symbols of the overlay code using
  2007.  
  2008. COP FLUSH SYMBOL "overlaydemo" FIRSTHUNK 0x<addr>
  2009.  
  2010. where addr is the address of the breakpoint you wrote down before.
  2011.  
  2012. One caveat using overlays is, that the structure of the overlay table
  2013. depends on the overlay manager the program uses. There are quite a lot
  2014. of them, however, COP only knows the default one supplied with the
  2015. linker BLink or SLink. As an example, the overlay structure of
  2016. DPaint II or COP (yes, that's me...) is private and is not supported
  2017. by COP. In this case, you cannot load symbols which are placed in the
  2018. overlay nodes, sorry.
  2019.  
  2020.  
  2021. If you want to use COP with the shapeshifter macintosh emulator, I suggest
  2022. the following command line:
  2023.  
  2024. COP FASTVBR MACMODE DDT S:Mac.ddt
  2025.  
  2026. plus your prefered keymap and display settings. COP can be entered from
  2027. the macintosh finder interface thru the hot key, as usual. Once entered,
  2028. the hardware traps are captured by COP, not by the MacOs. However, the
  2029. system failures (except those generated by hardware traps) are still left
  2030. to the Os. This might change in a future release.
  2031.  
  2032.  
  2033.  
  2034. XII) Syntax of a data description table
  2035. -----------------------------------------------------------------------------
  2036.  
  2037. The data description table contains information about labels, that are
  2038. litaral names given to addresses to make code more readable. COP intro-
  2039. duces a new concept of label creation not available with any other de-
  2040. bugger.
  2041. The labels are sorted by "type", as there are:
  2042.  
  2043. -       absolute labels, refering to one static address in memory.
  2044.         This is the only type of label most debuggers support.
  2045.  
  2046. -       equates. Those are simply names for numerical constants and
  2047.         are never used in actual disassembling. You may use it, how-
  2048.         ever, in expressions (and, in a release to come, in the
  2049.         microassembler)
  2050.         Typical equates are offsets of fields in structures.
  2051.  
  2052. -       node relative labels. If COP finds a specific base pointer
  2053.         points to a named exec-node structure (e.g. a library), this
  2054.         type of label is used to generate a name for the offset from
  2055.         the base of the node to the piece of memory which is addressed.
  2056.         A typical case is a entry point in a library, but also the full
  2057.         structure of a library can be addressed like that. So the default
  2058.         ddt includes the whole structure of execbase and gfxbase.
  2059.         Since the linking is done in the run time, it is not necessary
  2060.         to open these nodes, and the nodes even does not need to exist in
  2061.         memory while creating the labels.
  2062.  
  2063. -       address relative. This type is currently not used, but is
  2064.         useful if a base register is setup to point to the data region
  2065.         of a program. Typically, this will be a5 or a4.
  2066.  
  2067. -       a guru equate. This special type is used for giving readable
  2068.         names to guru meditations and is never used by the disassembler,
  2069.         but by the REGS.G instruction.
  2070.  
  2071. -       bit definitons. Useful for giving readable names to bits, but
  2072.         not used by the disassembler (there are way to many of them).
  2073.  
  2074. -       New with version 1.52 of COP, lineA-emulators can be named, too.
  2075.         These traps are never used by the AmigaOs, but function as Os-
  2076.         calls under a macintosh or Atari-ST emulation.
  2077.         
  2078. The syntax of a ddt file is a strange mixture of the syntax of the CBM
  2079. .fd-files and assembler include files, so you can use your .FD-files
  2080. and include files WITHOUT ANY CHANGE, provided you use the CBM macros
  2081. defined in exec/types.i and provided that you do not use forward 
  2082. references, as they are not supported.
  2083.  
  2084. Entries in the DDT are
  2085. i)      COPDDT-commands, a superset of the commands in the .fd files.
  2086.         COPDDT-commands are preceeded by two hashmarks and MUST be placed
  2087.         in the very first row.
  2088. ii)     Pure labels and function entries are given by their names and must 
  2089.         placed in the first row of the file, like labels in assembly
  2090.         language. As a special case, a label might be followed by a
  2091.         EQU or SET opcode. The first produces an equate label with
  2092.         a given value, and the second is ignored by COP since it is
  2093.         only used to keep track of the include files.
  2094.         If no value is given for a label, the contents is taken from
  2095.         the offset-counter which can be set by ##offset or ##bias.
  2096.         The type of the labels can be set by a COPDDT command pre-
  2097.         ceeding the label, except for labels defined by EQU, which
  2098.         will always be equates.
  2099.         A pure label without EQU will always increment the ##offset
  2100.         counter by a size which can be set by ##increment.
  2101. iii)    Pseudoassembler commands which are named like the default CBM-
  2102.         macros in the exec/types.i file. They mostly define a label of
  2103.         a type defined by some COPDDT command above, and the value
  2104.         is also taken from the ##offset counter. However, the 
  2105.         increment depends on the pseudoassembler command.
  2106. iv)     Comments are introduced by a colon or an asterisk like in 
  2107.         assembly language.
  2108.  
  2109. Here the COPDDT-commands:
  2110. ##node name             Setup the next labels as labels relative to the
  2111.                         node with the given name. Should be used for
  2112.                         library offsets.
  2113.  
  2114. ##vectors name        Identical to ##node, except that it defines function
  2115.             vectors. The label values should be negative.
  2116.  
  2117. ##guru                  Setup the next labels as numbers of guru-meditations
  2118.  
  2119. ##absolute              Setup the next labels as absolute addresses.
  2120.                         Never used with the Amiga-Os, since there is only
  2121.                         one fixed address (AbsExecBase), which is already
  2122.                         defined as a label. However, this type is used for
  2123.                         the low-memory variables of the macintosh Os
  2124.                         (what a horror !)
  2125. ##relative <expr>       Setup the next labels as offsets to the address
  2126.                         given by <expr>, which need not to be a number,
  2127.                         and may contain other evaluable labels. However,
  2128.                         forward references are not supported.
  2129. ##equate                Setup the next labels as pure equates.
  2130. ##linea                 Setup the next labels as line-a traps, as used by
  2131.                         the MacOs and atari ST. Useless for amiga.
  2132. ##offset <expr>         Set the offset of the next labels to come to their
  2133.                         base. With amiga only useful for labels of ##node, 
  2134.                         ##relative or ##equate type, since there is only 
  2135.                         one fixed absolute address in the amiga and no
  2136.                         line-A emulators. Useful for ##absolute and ##linea
  2137.                         under MacOs and Atari ST.
  2138. ##bias <expr>           Set the negative offset of the next labels. Will
  2139.                         be used by .fd files to set library entries and is
  2140.                         identical to ##offset except that the value of
  2141.                         <expr> is inverted (sign-changed).
  2142. ##increment <expr>      Sets the default incrementation value of the offset
  2143.                         counter. Should be set to -6 prior to including
  2144.                         .fd files, since each entry takes up 6 bytes, and
  2145.                         libraries grow to lower addresses. If you want to
  2146.                         define a table of LONGs, set the increment to 4.
  2147.                         This value is added to the ##offset counter every-
  2148.                         time a pure label without a size gets defined.
  2149.                         Function entries in a .fd file are "pure labels"
  2150.                         in the sense of COPDDT.
  2151. ##base name             Define the name of a library base. Used by the
  2152.                         .fd files. Will define a label of offset
  2153.                         zero.
  2154. ##include name          Include another file in the ddt. There is NO
  2155.                         check for cyclic dependence, so WATCH OUT !
  2156.                         If the name contains spaces, include it in double
  2157.                         quotes.
  2158. ##end                   End an ddt file. Also used by .fd files.
  2159.  
  2160. ##private               Quietly ignored by COP, only used in fd-files
  2161. ##public                Also ignored.
  2162.  
  2163. Empty lines or lines starting with a colon or a star are read as comment-
  2164. lines and are ignored, too.
  2165.  
  2166. Label definitions:
  2167. A "pure" label is defined by giving only its name starting in the
  2168. first row of a line, like this:
  2169.  
  2170. ##absolute 8            ; Labels are of absolute type
  2171. ##increment 1           ; Set the increment of pure labels
  2172. mylabel                 ; comments are welcome ! This label gets the value 8
  2173. nextlabel               ; and this one 9, since the increment is 1
  2174.  
  2175. The value of the label to be defined is contained in the offset counter,
  2176. and it will be incremented by the value in ##increment every time.
  2177.  
  2178. Since fd-files contain functions and arguments, a (pure) label name is 
  2179. cut in the first occurance of a left bracket:
  2180.  
  2181. myFunc(foo)(a0)         ;this label gets called "myFunc" and got the value 10
  2182.  
  2183. Labels can be set to given values using the EQU pseudoassembler directive.
  2184. These "unpure" labels neither need the offset counter nor increment it.
  2185. All labels generated by this syntax are of equate type, regardless of the
  2186. previous COPDDT command.
  2187. TRUE            EQU     1       ; an equate. Can be evaluated, but is
  2188.                                 ; not used by the disassembler
  2189.                                 ; also, the offset counter is untouched
  2190.  
  2191.  
  2192. The set directive of assembly language is known, but will be ignored without
  2193. any checking
  2194. ARGC            SET     §       ;in assembly language syntactically wrong,
  2195.                                 ;but completely ignored by COP.
  2196.  
  2197. The same goes for lines between a MACRO and a ENDM directive, since
  2198. COP does not support macros (and I think never will..).
  2199.  
  2200.  
  2201. Pseudoassembler commands:
  2202. They are called "pseudoassembler commands" cause they define labels in
  2203. assembly style, rather than .fd style. All macros in exec/types.i are
  2204. "emulated". The type of labels generated by them depend on the pre-
  2205. ceding COPDDT command, like ##absolute will generate absolute labels.
  2206. The value of the labels is given, as above, by the offset counter. This
  2207. counter can be set with the ##offset COPDDT command or the STRUCTURE
  2208. directive, and will be incremented by a value determinated by the
  2209. directive, unlike pure labels, which cause the value of ##increment
  2210. to be added.
  2211.  
  2212. Pseudoassembler directives MUST NOT start at the beginning of a line, but
  2213. MUST be preceded by spaces or TAB characters, like in assembly language.
  2214.  
  2215. Known directives are:
  2216.  
  2217.         STRUCTURE name,<expr>
  2218. Define a new label of given name as the base of a structure. The offset
  2219. counter will be initialized by <expr>, that is, the structure containes
  2220. unnamed field in the beginning of the size given by offset. The value
  2221. of the label defined will be zero relatively to a base, which can be
  2222. setup by ##node or ##relative. Defining an absolute structure does not
  2223. make much sense in this system.
  2224.  
  2225.         STRUCT name,<expr>
  2226. Define a substructure in a structure, that is, generate a label of given
  2227. name with the value as the value of the offset counter, and of type
  2228. given by a preceding COPDDT command. The offset counter is incremented by
  2229. the value of <expr> afterwards.
  2230.  
  2231.         LABEL name
  2232. Define a label with the value of the offset counter, which is not
  2233. incremented at all.
  2234.  
  2235.         UBYTE name[,<expr>]
  2236. Define one single byte, or array of bytes by generating a label. Its 
  2237. value is given by the offset counter, and its type is given by a preceding
  2238. COPDDT command. The offsetcounter is incremented by 1, if the expression
  2239. is ommited, or 1x<expr> to generate an array.
  2240.  
  2241.         BYTE name[,<expr>]
  2242. Same as byte.
  2243.  
  2244.         UWORD name[,<expr>]
  2245. Define one single word, or array of words. Works like BYTE, but the offset
  2246. counter is incremented by 2 or 2x<expr>. If the offset counter is odd, it
  2247. is rounded to the next even number.
  2248.  
  2249.         WORD name[,<expr>]
  2250. Same.
  2251.  
  2252.         BOOL name[,<expr>]
  2253. Same.
  2254.  
  2255.         ULONG name[,<expr>]
  2256. Defines one long word, or array of longwords. Increments by 4 or 4x<expr>
  2257. and alignes offset counter.
  2258.  
  2259.         LONG name[,<expr>]
  2260. Same.
  2261.  
  2262.         APTR name[,<expr>]
  2263. Same.
  2264.  
  2265.         CPTR name[,<expr>]
  2266. Same.
  2267.  
  2268.         FPTR name[,<expr>]
  2269. Same.
  2270.  
  2271.         FLOAT name[,<expr>]
  2272. Same.
  2273.  
  2274.         DOUBLE name[,<expr>]
  2275. Defines a IEEE-double precision entry or array. Increments the offset counter
  2276. by 8 or 8x<expr> and alignes it.
  2277.  
  2278.         UQUAT name[,<expr>]
  2279. Same.
  2280.  
  2281.         QUAT name[,<expr>]
  2282. Same.
  2283.  
  2284.         EXTENDED name[,<expr>]
  2285. Introduced into COP, defines MC68881 extended precision entry or array.
  2286. Increments the offset by 12 or 12x<expr> and aligns it.
  2287.  
  2288.         ALIGNWORD
  2289. Explicitly aligns the offset counter to the next word.
  2290.  
  2291.         ALIGNLONG
  2292. Align the offset counter to the next long word.
  2293.  
  2294.         ENUM [<expr>]
  2295. Initializes the ENUM-counter by the given value. Does not generate any label.
  2296.  
  2297.         ENUMITEM name
  2298. Generate a label of equate type. The value is given by the equate counter,
  2299. which will be incremented by one after the definition.
  2300.  
  2301.         BITDEF pre,post,<expr>
  2302. Generate two (!) labels. The first is of bit-type and will be named 
  2303. "preB_post" and will have the value given by <expr>. The second will be
  2304. named "preF_post", is of equate type and has the value of 1 << <expr>.
  2305.  
  2306.         IFD,IFND,ENDC
  2307. Ignored by COP
  2308.  
  2309.         INCLUDE
  2310. Ignored by COP. To include something, use the COPDDT command ##include.
  2311. This was mainly done to avoid unnecessary includes and to give the
  2312. control what will be included to the main DDT-file.
  2313.  
  2314.         LIBINIT
  2315.         LIBDEF
  2316. Also ignored by COP
  2317.  
  2318.         MACRO
  2319.         ...
  2320.         ENDM
  2321. Lines between MACRO and ENDM are ignored by COP, since it does not support
  2322. macros.
  2323.  
  2324.  
  2325. As noted above, the set of supported commands was choosen in that way, such
  2326. that all orignal CBM-includes and .fd files can be used without a change.
  2327. Support of other style assembly include files (like DevPac's rs-counter)
  2328. are not supported and never will.
  2329. It is, however, sometimes necessary to explicitly define labels on one's
  2330. own. This happens mostly if the orginal include file defines useful
  2331. constants that should be relative to a base as equates. An example is
  2332. the definition of DOSBase in dos/dosextens.i. Since you cannot make
  2333. all labels relative to DOSBase, one must take this definition out
  2334. of the file.
  2335. Defining DOSBase as equates and not as node relative is of course not
  2336. illegal in COP, but will be of no use for the disassembler, since it 
  2337. ignores equates (there are to many of them to be of any use). This was,
  2338. as a second example, necessary in defining the hardware offsets. 
  2339. Originally given as equates, they are now relative to the base of 
  2340. the custom chip set. See the included example ddt file. 
  2341.  
  2342.  
  2343. XIII) Shell scripts
  2344. -----------------------------------------------------------------------------
  2345.  
  2346. Three shell scripts are provided with COP, to simplify work:
  2347.  
  2348. -Debug          Accepts a program name (full path required) and its
  2349.                 arguments to be debugged by COP. Will load the program
  2350.                 as if started from the Shell and set a breakpoint at the
  2351.                 first hunk.
  2352.  
  2353. -WBDebug        Accept a workbench program and, optionally, a secondary
  2354.                 selection, without .info. Starts the program and supplies
  2355.                 the arguments thru a WBStartup message, as if started from
  2356.                 the workbench.
  2357.  
  2358. -Calc           Evaluates the supplied argument. Labels are welcome, and
  2359.                 the radix defaults to decimal. However, problems may
  2360.                 arise if you use hex numbers cause the $ can cause
  2361.                 conflicts with defined shell variables. In this case,
  2362.                 enclose the argument in double quotes.
  2363.  
  2364.  
  2365. XIV) COP and the Enforcer
  2366. -----------------------------------------------------------------------------
  2367. COP 1.56 supports the Enforcer program if run on a MC68020 or MC68030. I plan
  2368. to add support for the MC68060, but don't have enough documentations about
  2369. this processor and the Enforcer replacement "CyberGuard".
  2370.  
  2371. There are two ways to run the enforcer together with COP, depending on which
  2372. output you need.
  2373.  
  2374. Method I):    Start the enforcer first, then run COP. Don't remove the
  2375. Enforcer later.
  2376.  
  2377. This will redirect Enforcer hints directly to COP. Faulty programs will cause
  2378. a bus error exception, and you're now able to debug these programs directly.
  2379. The enforcer won't cause any ouput, running "Sushi" is not necessary.
  2380.  
  2381. DO NOT SUPPLY THE FASTVBR COMMAND LINE SWITCH IN THIS CASE as this will over-
  2382. write the Enforcer exception table. Besides that this exception table is
  2383. already in FASTMEM, so this option is unnecessary.
  2384.  
  2385.  
  2386. Method II):    Start COP first, then load the Enforcer. It is possible to
  2387. remove the Enforcer later on, however.
  2388.  
  2389. The enforcer will work as usual with this setting, COP won't interfere in this
  2390. case.
  2391.  
  2392.  
  2393. XV) Plans
  2394. -----------------------------------------------------------------------------
  2395.  
  2396. - Making the chip-buffer more transparent
  2397. - Better memory chunk support
  2398. - better disassembler, parts are already working
  2399. - a microassembler (in preparation)
  2400. - wildcards in node matching
  2401. - bitdefs should really be relative to something, but system includes
  2402.   do not give the information
  2403. - more macintosh support, thru a mac INIT.
  2404.  
  2405. In the next time, there won't be...
  2406.  
  2407. - a floppy or harddisk support. There are so many filing systems and device
  2408.   drivers and I think using the 20K or more needed to implement this stuff
  2409.   can be used a better way.
  2410. - a MMU support, cause I do not plan to invest any money into my #"&$!@
  2411.   computer, I'll better buy a new one (which will be a more stable one, so
  2412.   no AMIGA anymore...)
  2413.  
  2414.  
  2415. XVI) Final remarks
  2416. -----------------------------------------------------------------------------
  2417.  
  2418. COP should not be crunched or compacted, since COP uses an internal overlay
  2419. format to load the debugger code if needed. To enter COP later with a
  2420. COP DISPLAY GO or equiv. the startup segment is loaded to memory only.
  2421.  
  2422. I wrote COP three years ago (1993) to find the reason of many crashes that
  2423. occured in my system. I found that most debuggers I knew were not
  2424. able to debug a system with execbase out of order or input.device beeing
  2425. crashed. The first debugger I used to accomplish this task was the ROMWack,
  2426. a very simple, but nevertheless useful one. 
  2427. I needed a year to complete the first release of COP, so I can appreciate a
  2428. programmers work and you should do so, too. Please use COP to find bugs
  2429. in your own code only, whenever every other debugger fails, e.g.
  2430. interrupt code or reset resident code. Use COP to find the reason of
  2431. system crashes that crash normal debuggers, but PLEASE DO NOT USE COP TO
  2432. FUMBLE IN FOREIGN CODE, since this will prevent people from writing
  2433. good programs. Not everthing is public domain today.
  2434.  
  2435. This program is decidated to all the bubling idiots that debug own code
  2436. up to 4 a.m. in the morning ("It MUST work...").
  2437.  
  2438.  
  2439. Thank goes to:
  2440. -Oliver Spaniol for letting me debug this proggy on his '60.
  2441.  
  2442.  
  2443.  
  2444. If you like this program, if you have any suggestions, if you want to get a
  2445. newer release of COP, write to:
  2446.  
  2447.  
  2448. Thomas Richter
  2449. Rühmkorffstraße 10 A
  2450.  
  2451. D-12209 Berlin
  2452.  
  2453. Germany
  2454. -------
  2455.  
  2456. or send electronic mail thru internet to
  2457.  
  2458. thor@einstein.math.tu-berlin.de                 - or -
  2459. thorj@granit.cs.tu-berlin.de
  2460.  
  2461.  
  2462. There's also a web site you should try:
  2463.  
  2464. WWW:    http://www.math.tu-berlin.de/~thor/thor/index.html
  2465.  
  2466.  
  2467.  
  2468. It might be possible that COP does not work on YOUR Amiga, some parts of
  2469. the code are very tricky and hardware dependent. I tried to avoid such
  2470. problems, but one can never know. If COP fails on your computer, send
  2471. me a mail and descripe as best as possible your problems. However, debugging
  2472. by mail is a complicate task....
  2473.  
  2474.  
  2475. Thank you for reading and have a good time...
  2476.  
  2477.         THOR    (October 1997)
  2478.  
  2479.